Merge "Update documentation to reflect the old approach not working." into ics-mr1
diff --git a/docs/html/design/get-started/ui-overview.html b/docs/html/design/get-started/ui-overview.html
index b08c743..bd5ff9c 100644
--- a/docs/html/design/get-started/ui-overview.html
+++ b/docs/html/design/get-started/ui-overview.html
@@ -153,12 +153,12 @@
</div>
</div>
-<h2>UI Bars</h2>
+<h2>System Bars</h2>
-<p>The UI bars are screen areas dedicated to the display of notifications, communication of device
-status, and device navigation. Typically the UI bars are displayed concurrently with your app. Apps
-that display immersive content, such as movies or images, can temporarily hide the UI bars to allow
-the user to enjoy full screen content without distraction.</p>
+<p>The system bars are screen areas dedicated to the display of notifications, communication of device
+status, and device navigation. Typically the system bars are displayed concurrently with your app.
+Apps that display immersive content, such as movies or images, can temporarily hide the system bars
+to allow the user to enjoy full screen content without distraction.</p>
<img src="../static/content/ui_overview_system_ui.png">
@@ -177,8 +177,9 @@
Recents, and also displays a menu for apps written for Android 2.3 or earlier.</p>
</li>
<li>
-<h4>System Bar</h4>
-<p>Combines the status and navigation bars for display on tablet form factors.</p>
+<h4>Combined Bar</h4>
+<p>On tablet form factors the status and navigation bars are combined into a single bar at the
+ bottom of the screen.</p>
</li>
</ol>
diff --git a/docs/html/design/patterns/actionbar.html b/docs/html/design/patterns/actionbar.html
index 99ae2d7..911c549 100644
--- a/docs/html/design/patterns/actionbar.html
+++ b/docs/html/design/patterns/actionbar.html
@@ -133,7 +133,7 @@
you wish.
Important: If the app is currently not displaying the top-level screen, be sure to display the Up
caret to the left of the app icon, so the user can navigate up the hierarchy. For more discussion of
-Up navigation, see the "Navigation" pattern.
+Up navigation, see the <a href="../patterns/navigation.html">Navigation</a> pattern.
<div class="figure">
<img src="../static/content/action_bar_pattern_up_app_icon.png">
@@ -369,6 +369,22 @@
<p>If either F, I, or T apply, then it's appropriate for the action bar. Otherwise, it belongs in the
action overflow.</p>
+<p>
+
+Pre-defined glyphs should be used for certain common actions such as "refresh" and "share." The
+download link below provides a package with icons that are scaled for various screen densities and
+are suitable for use with the Holo Light and Holo Dark themes. The package also includes unstyled
+icons that you can modify to match your theme, in addition to Adobe® Illustrator® source
+files for further customization.
+
+</p>
+<p>
+
+<a href="../static/download/action_bar_icons-v4.0.zip">Download the Action Bar Icon
+Pack</a>
+
+</p>
+
<div class="layout-content-row">
<div class="layout-content-col span-6">
diff --git a/docs/html/design/patterns/app-structure.html b/docs/html/design/patterns/app-structure.html
index b87f402..fb9205b 100644
--- a/docs/html/design/patterns/app-structure.html
+++ b/docs/html/design/patterns/app-structure.html
@@ -159,9 +159,9 @@
<img src="../static/content/app_structure_market.png">
<div class="figure-caption">
- Market's start screen primarily allows navigation into the stores for Apps, Music, Books, and
- Games. It is also enriched with tailored recommendations and promotions that surface content
- of interest to the user. Search is readily available from the action bar.
+ Market's start screen primarily allows navigation into the stores for Apps, Music, Books,
+ Movies and Games. It is also enriched with tailored recommendations and promotions that
+ surface content of interest to the user. Search is readily available from the action bar.
</div>
</div>
diff --git a/docs/html/design/patterns/navigation.html b/docs/html/design/patterns/navigation.html
index aabfc39..cad3682 100644
--- a/docs/html/design/patterns/navigation.html
+++ b/docs/html/design/patterns/navigation.html
@@ -131,7 +131,7 @@
<p>The Back key also supports a few behaviors not directly tied to screen-to-screen navigation:</p>
<ul>
<li>Back dismisses floating windows (dialogs, popups)</li>
-<li>Back dismisses contextual action bars, and remove highlight from selected items</li>
+<li>Back dismisses contextual action bars, and removes the highlight from the selected items</li>
<li>Back hides the onscreen keyboard (IME)</li>
</ul>
<h2>Navigation Within Your App</h2>
@@ -189,18 +189,19 @@
<h4>App-to-app navigation</h4>
<p>When navigating deep into your app's hierarchy directly from another app via an intent, Back will
return to the referring app.</p>
-<p>The Up button is handled is follows:
+<p>The Up button is handled as follows:
- If the destination screen is typically reached from one particular screen within your app, Up
should navigate to that screen.
- Otherwise, Up should navigate to the topmost ("Home") screen of your app.</p>
-<p>For example, after choosing to share a book being view in Market, the user navigates directly to the
-Gmail's compose screen. From there, Up returns to the Inbox (which happens to be both the typical
-referrer to compose, as well as the topmost screen of the app), while Back returns to Market.</p>
+<p>For example, after choosing to share a book being viewed in Market, the user navigates directly to
+Gmail's compose screen. From there, Up returns to the Inbox (which happens to be both the
+typical referrer to compose, as well as the topmost screen of the app), while Back returns to
+Market.</p>
<img src="../static/content/navigation_from_outside_up.png">
<h4>System-to-app navigation</h4>
-<p>If the your app was reached via the system mechanisms of notifications or home screen widgets, Up
+<p>If your app was reached via the system mechanisms of notifications or home screen widgets, Up
behaves as described for app-to-app navigation, above.</p>
<p>For the Back key, you should make navigation more predictably by inserting into the task's back
stack the complete upward navigation path to the app's topmost screen. This way, a user who has
diff --git a/docs/html/design/patterns/notifications.html b/docs/html/design/patterns/notifications.html
index acec306..c5045aed 100644
--- a/docs/html/design/patterns/notifications.html
+++ b/docs/html/design/patterns/notifications.html
@@ -200,7 +200,7 @@
the user is taken to a hierarchy level below your app's top-level, insert navigation into your app's
back stack to allow them to navigate to your app's top level using the system back key. For more
information, see the chapter on <em>System-to-app navigation</em> in the
-<a href="../patterns/notifications.html">Navigation</a> design pattern.</p>
+<a href="../patterns/navigation.html">Navigation</a> design pattern.</p>
<h4>Timestamps for time sensitive events</h4>
<p>By default, standard Android notifications include a timestamp in the upper right corner. Consider
whether the timestamp is valuable in the context of your notification. If the timestamp is not
diff --git a/docs/html/design/static/download/action_bar_icons-v4.0.zip b/docs/html/design/static/download/action_bar_icons-v4.0.zip
new file mode 100644
index 0000000..4568894
--- /dev/null
+++ b/docs/html/design/static/download/action_bar_icons-v4.0.zip
Binary files differ
diff --git a/docs/html/design/style/iconography.html b/docs/html/design/style/iconography.html
index 663770b..5d5d200 100644
--- a/docs/html/design/style/iconography.html
+++ b/docs/html/design/style/iconography.html
@@ -193,10 +193,28 @@
<h2 id="actionbar">Action Bar</h2>
-<p>Action bar icons are graphic buttons that represent the most important actions people can take
-within your app. Each one should employ a simple metaphor representing a single concept that most
-people can grasp at a glance.</p>
+<p>
+Action bar icons are graphic buttons that represent the most important actions people can take
+within your app. Each one should employ a simple metaphor representing a single concept that most
+people can grasp at a glance.
+
+</p>
+<p>
+
+Pre-defined glyphs should be used for certain common actions such as "refresh" and "share." The
+download link below provides a package with icons that are scaled for various screen densities and
+are suitable for use with the Holo Light and Holo Dark themes. The package also includes unstyled
+icons that you can modify to match your theme, in addition to Adobe® Illustrator® source
+files for further customization.
+
+</p>
+<p>
+
+<a href="../static/download/action_bar_icons-v4.0.zip">Download the Action Bar Icon
+Pack</a>
+
+</p>
<div class="layout-content-row">
<div class="layout-content-col span-4">
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index ee4c48e..4e5badd 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -87,10 +87,24 @@
<span class="en">Content Providers</span>
</a></div>
<ul>
- <li><a href="<?cs var:toroot ?>guide/topics/providers/calendar-provider.html">
- <span class="en">Calendar Provider</span></a>
- <span class="new">new!</span>
- </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/topics/providers/content-provider-basics.html">
+ <span class="en">Content Provider Basics</span>
+ </a>
+ <span class="new">new!</span>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/topics/providers/content-provider-creating.html">
+ <span class="en">Creating a Content Provider</span>
+ </a>
+ <span class="new">new!</span>
+ </li>
+ <li>
+ <a href="<?cs var:toroot ?>guide/topics/providers/calendar-provider.html">
+ <span class="en">Calendar Provider</span>
+ </a>
+ <span class="new">new!</span>
+ </li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html">
diff --git a/docs/html/guide/practices/ui_guidelines/icon_design.jd b/docs/html/guide/practices/ui_guidelines/icon_design.jd
index 96aecf5..1c66185 100644
--- a/docs/html/guide/practices/ui_guidelines/icon_design.jd
+++ b/docs/html/guide/practices/ui_guidelines/icon_design.jd
@@ -42,8 +42,6 @@
Templates Pack, v2.3 »</a></li>
<li><a href="{@docRoot}shareables/icon_templates-v2.0.zip">Android Icon
Templates Pack, v2.0 »</a></li>
-<li><a href="{@docRoot}shareables/icon_templates-v1.0.zip">Android Icon
-Templates Pack, v1.0 »</a></li>
</ol>
<h2>See also</h2>
diff --git a/docs/html/guide/topics/providers/content-provider-basics.jd b/docs/html/guide/topics/providers/content-provider-basics.jd
new file mode 100644
index 0000000..40b5c3f
--- /dev/null
+++ b/docs/html/guide/topics/providers/content-provider-basics.jd
@@ -0,0 +1,1215 @@
+page.title=Content Provider Basics
+@jd:body
+<div id="qv-wrapper">
+<div id="qv">
+
+
+ <!-- In this document -->
+<h2>In this document</h2>
+<ol>
+ <li>
+ <a href="#Basics">Overview</a>
+ <ol>
+ <li>
+ <a href="#ClientProvider">Accessing a provider</a>
+ </li>
+ <li>
+ <a href="#ContentURIs">Content URIs</a>
+ </li>
+ </ol>
+ </li>
+ <li>
+ <a href="#SimpleQuery">Retrieving Data from the Provider</a>
+ <ol>
+ <li>
+ <a href="#RequestPermissions">Requesting read access permission</a>
+ </li>
+ <li>
+ <a href="#Query">Constructing the query</a>
+ </li>
+ <li>
+ <a href="#DisplayResults">Displaying query results</a>
+ </li>
+ <li>
+ <a href="#GettingResults">Getting data from query results</a>
+ </li>
+ </ol>
+ </li>
+ <li>
+ <a href="#Permissions">Content Provider Permissions</a>
+ </li>
+ <li>
+ <a href="#Modifications">Inserting, Updating, and Deleting Data</a>
+ <ol>
+ <li>
+ <a href="#Inserting">Inserting data</a>
+ </li>
+ <li>
+ <a href="#Updating">Updating data</a>
+ </li>
+ <li>
+ <a href="#Deleting">Deleting data</a>
+ </li>
+ </ol>
+ </li>
+ <li>
+ <a href="#DataTypes">Provider Data Types</a>
+ </li>
+ <li>
+ <a href="#AltForms">Alternative Forms of Provider Access</a>
+ <ol>
+ <li>
+ <a href="#Batch">Batch access</a>
+ </li>
+ <li>
+ <a href="#Intents">Data access via intents</a>
+ </li>
+ </ol>
+ </li>
+ <li>
+ <a href="#ContractClasses">Contract Classes</a>
+ </li>
+ <li>
+ <a href="#MIMETypeReference">MIME Type Reference</a>
+ </li>
+</ol>
+
+ <!-- Key Classes -->
+<h2>Key classes</h2>
+ <ol>
+ <li>
+ {@link android.content.ContentProvider}
+ </li>
+ <li>
+ {@link android.content.ContentResolver}
+ </li>
+ <li>
+ {@link android.database.Cursor}
+ </li>
+ <li>
+ {@link android.net.Uri}
+ </li>
+ </ol>
+
+ <!-- Related Samples -->
+<h2>Related Samples</h2>
+ <ol>
+ <li>
+ <a
+ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List2.html">
+ Cursor (People)</a>
+ </li>
+ <li>
+ <a
+ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html">
+ Cursor (Phones)</a>
+ </li>
+ </ol>
+
+ <!-- See also -->
+<h2>See also</h2>
+ <ol>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/content-provider-creating.html">
+ Creating a Content Provider</a>
+ </li>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/calendar-provider.html">
+ Calendar Provider</a>
+ </li>
+ </ol>
+</div>
+</div>
+
+ <!-- Intro paragraphs -->
+<p>
+ A content provider manages access to a central repository of data. The provider and
+ is part of an Android application, which often provides its own UI for working with
+ the data. However, content providers are primarily intended to be used by other
+ applications, which access the provider using a provider client object. Together, providers
+ and provider clients offer a consistent, standard interface to data that also handles
+ inter-process communication and secure data access.
+</p>
+<p>
+ This topic describes the basics of the following:
+</p>
+ <ul>
+ <li>How content providers work.</li>
+ <li>The API you use retrieve data from a content provider.</li>
+ <li>The API you use to insert, update, or delete data in a content provider.</li>
+ <li>Other API features that facilitate working with providers.</li>
+ </ul>
+
+ <!-- Basics -->
+<h2 id="Basics">Overview</h2>
+<p>
+ A content provider presents data to external applications as one or more tables that are
+ similar to the tables found in a relational database. A row represents an instance of some type
+ of data the provider collects, and each row in the column represents an individual piece of
+ data collected for an instance.
+</p>
+<p>
+ For example, one of the built-in providers in the Android platform is the user dictionary, which
+ stores the spellings of non-standard words that the user wants to keep. Table 1 illustrates what
+ the data might look like in this provider's table:
+</p>
+<p class="table-caption">
+ <strong>Table 1:</strong> Sample user dictionary table.
+</p>
+<table id="table1" style="width: 50%;">
+ <tr>
+ <th style="width:20%" align="center" scope="col">word</th>
+ <th style="width:20%" align="center" scope="col">app id</th>
+ <th style="width:20%" align="center" scope="col">frequency</th>
+ <th style="width:20%" align="center" scope="col">locale</th>
+ <th style="width:20%" align="center" scope="col">_ID</th>
+ </tr>
+ <tr>
+ <td align="center" scope="row">mapreduce</td>
+ <td align="center">user1</td>
+ <td align="center">100</td>
+ <td align="center">en_US</td>
+ <td align="center">1</td>
+ </tr>
+ <tr>
+ <td align="center" scope="row">precompiler</td>
+ <td align="center">user14</td>
+ <td align="center">200</td>
+ <td align="center">fr_FR</td>
+ <td align="center">2</td>
+ </tr>
+ <tr>
+ <td align="center" scope="row">applet</td>
+ <td align="center">user2</td>
+ <td align="center">225</td>
+ <td align="center">fr_CA</td>
+ <td align="center">3</td>
+ </tr>
+ <tr>
+ <td align="center" scope="row">const</td>
+ <td align="center">user1</td>
+ <td align="center">255</td>
+ <td align="center">pt_BR</td>
+ <td align="center">4</td>
+ </tr>
+ <tr>
+ <td align="center" scope="row">int</td>
+ <td align="center">user5</td>
+ <td align="center">100</td>
+ <td align="center">en_UK</td>
+ <td align="center">5</td>
+ </tr>
+</table>
+<p>
+ In table 1, each row represents an instance of a word that might not be
+ found in a standard dictionary. Each column represents some data for that word, such as the
+ locale in which it was first encountered. The column headers are column names that are stored in
+ the provider. To refer to a row's locale, you refer to its <code>locale</code> column. For
+ this provider, the <code>_ID</code> column serves as a "primary key" column that
+ the provider automatically maintains.
+</p>
+<p class="note">
+ <strong>Note:</strong> A provider isn't required to have a primary key, and it isn't required
+ to use <code>_ID</code> as the column name of a primary key if one is present. However,
+ if you want to bind data from a provider to a {@link android.widget.ListView}, one of the
+ column names has to be <code>_ID</code>. This requirement is explained in more detail in the
+ section <a href="#DisplayResults">Displaying query results</a>.
+</p>
+<h3 id="ClientProvider">Accessing a provider</h3>
+<p>
+ An application accesses the data from a content provider with
+ a {@link android.content.ContentResolver} client object. This object has methods that call
+ identically-named methods in the provider object, an instance of one of the concrete
+ subclasses of {@link android.content.ContentProvider}. The
+ {@link android.content.ContentResolver} methods provide the basic
+ "CRUD" (create, retrieve, update, and delete) functions of persistent storage.
+</p>
+<p>
+ The {@link android.content.ContentResolver} object in the client application's
+ process and the {@link android.content.ContentProvider} object in the application that owns
+ the provider automatically handle inter-process communication.
+ {@link android.content.ContentProvider} also acts as an abstraction layer between its
+ repository of data and the external appearance of data as tables.
+</p>
+<p class="note">
+ <strong>Note:</strong> To access a provider, your application usually has to request specific
+ permissions in its manifest file. This is described in more detail in the section
+ <a href="#Permissions">Content Provider Permissions</a>
+</p>
+<p>
+ For example, to get a list of the words and their locales from the User Dictionary Provider,
+ you call {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ ContentResolver.query()}.
+ The {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ query()} method calls the
+ {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
+ ContentProvider.query()} method defined by the User Dictionary Provider. The following lines
+ of code show a
+ {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ ContentResolver.query()} call:
+<p>
+<pre>
+// Queries the user dictionary and returns results
+mCursor = getContentResolver().query(
+ UserDictionary.Words.CONTENT_URI, // The content URI of the words table
+ mProjection, // The columns to return for each row
+ mSelectionClause // Selection criteria
+ mSelectionArgs, // Selection criteria
+ mSortOrder); // The sort order for the returned rows
+</pre>
+<p>
+ Table 2 shows how the arguments to
+ {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ query(Uri,projection,selection,selectionArgs,sortOrder)} match an SQL SELECT statement:
+</p>
+<p class="table-caption">
+ <strong>Table 2:</strong> Query() compared to SQL query.
+</p>
+<table id="table2" style="width: 75%;">
+ <tr>
+ <th style="width:25%" align="center" scope="col">query() argument</th>
+ <th style="width:25%" align="center" scope="col">SELECT keyword/parameter</th>
+ <th style="width:50%" align="center" scope="col">Notes</th>
+ </tr>
+ <tr>
+ <td align="center"><code>Uri</code></td>
+ <td align="center"><code>FROM <em>table_name</em></code></td>
+ <td><code>Uri</code> maps to the table in the provider named <em>table_name</em>.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>projection</code></td>
+ <td align="center"><code><em>col,col,col,...</em></code></td>
+ <td>
+ <code>projection</code> is an array of columns that should be included for each row
+ retrieved.
+ </td>
+ </tr>
+ <tr>
+ <td align="center"><code>selection</code></td>
+ <td align="center"><code>WHERE <em>col</em> = <em>value</em></code></td>
+ <td><code>selection</code> specifies the criteria for selecting rows.</td>
+ </tr>
+ <tr>
+ <td align="center"><code>selectionArgs</code></td>
+ <td align="center">
+ (No exact equivalent. Selection arguments replace <code>?</code> placeholders in the
+ selection clause.)
+ </td>
+ </tr>
+ <tr>
+ <td align="center"><code>sortOrder</code></td>
+ <td align="center"><code>ORDER BY <em>col,col,...</em></code></td>
+ <td>
+ <code>sortOrder</code> specifies the order in which rows appear in the returned
+ {@link android.database.Cursor}.
+ </td>
+ </tr>
+</table>
+<h3 id="ContentURIs">Content URIs</h3>
+<p>
+ A <strong>content URI</strong> is a URI that identifies data in a provider. Content URIs
+ include the symbolic name of the entire provider (its <strong>authority</strong>) and a
+ name that points to a table (a <strong>path</strong>). When you call
+ a client method to access a table in a provider, the content URI for the table is one of
+ the arguments.
+</p>
+<p>
+ In the preceding lines of code, the constant
+ {@link android.provider.UserDictionary.Words#CONTENT_URI} contains the content URI of
+ the user dictionary's "words" table. The {@link android.content.ContentResolver}
+ object parses out the URI's authority, and uses it to "resolve" the provider by
+ comparing the authority to a system table of known providers. The
+ {@link android.content.ContentResolver} can then dispatch the query arguments to the correct
+ provider.
+</p>
+<p>
+ The {@link android.content.ContentProvider} uses the path part of the content URI to choose the
+ table to access. A provider usually has a <strong>path</strong> for each table it exposes.
+</p>
+<p>
+ In the previous lines of code, the full URI for the "words" table is:
+</p>
+<pre>
+content://user_dictionary/words
+</pre>
+<p>
+ where the <code>user_dictionary</code> string is the provider's authority, and
+ <code>words</code> string is the table's path. The string
+ <code>content://</code> (the <strong>scheme</strong>) is always present,
+ and identifies this as a content URI.
+</p>
+<p>
+ Many providers allow you to access a single row in a table by appending an ID value
+ to the end of the URI. For example, to retrieve a row whose <code>_ID</code> is
+ <code>4</code> from user dictionary, you can use this content URI:
+</p>
+<pre>
+Uri singleUri = ContentUri.withAppendedId(UserDictionary.Words.CONTENT_URI,4);
+</pre>
+<p>
+ You often use id values when you've retrieved a set of rows and then want to update or delete
+ one of them.
+</p>
+<p class="note">
+ <strong>Note:</strong> The {@link android.net.Uri} and {@link android.net.Uri.Builder} classes
+ contain convenience methods for constructing well-formed Uri objects from strings. The
+ {@link android.content.ContentUris} contains convenience methods for appending id values to
+ a URI. The previous snippet uses {@link android.content.ContentUris#withAppendedId(Uri, long)
+ withAppendedId()} to append an id to the UserDictionary content URI.
+</p>
+
+
+ <!-- Retrieving Data from the Provider -->
+<h2 id="SimpleQuery">Retrieving Data from the Provider</h2>
+<p>
+ This section describes how to retrieve data from a provider, using the User Dictionary Provider
+ as an example.
+</p>
+<p class="note">
+ For the sake of clarity, the code snippets in this section call
+ {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ ContentResolver.query()} on the "UI thread"". In actual code, however, you should
+ do queries asynchronously on a separate thread. One way to do this is to use the
+ {@link android.content.CursorLoader} class, which is described
+ in more detail in the <a href="{@docRoot}guide/topics/fundamentals/loaders.html">
+ Loaders</a> guide. Also, the lines of code are snippets only; they don't show a complete
+ application.
+</p>
+<p>
+ To retrieve data from a provider, follow these basic steps:
+</p>
+<ol>
+ <li>
+ Request the read access permission for the provider.
+ </li>
+ <li>
+ Define the code that sends a query to the provider.
+ </li>
+</ol>
+<h3 id="RequestPermissions">Requesting read access permission</h3>
+<p>
+ To retrieve data from a provider, your application needs "read access permission" for the
+ provider. You can't request this permission at run-time; instead, you have to specify that
+ you need this permission in your manifest, using the
+ <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">
+ <uses-permission></a></code> element and the exact permission name defined by the
+ provider. When you specify this element in your manifest, you are in effect "requesting" this
+ permission for your application. When users install your application, they implicitly grant
+ this request.
+</p>
+<p>
+ To find the exact name of the read access permission for the provider you're using, as well
+ as the names for other access permissions used by the provider, look in the provider's
+ documentation.
+</p>
+<p>
+ The role of permissions in accessing providers is described in more detail in the section
+ <a href="#Permissions">Content Provider Permissions</a>.
+</p>
+<p>
+ The User Dictionary Provider defines the permission
+ <code>android.permission.READ_USER_DICTIONARY</code> in its manifest file, so an
+ application that wants to read from the provider must request this permission.
+</p>
+<!-- Constructing the query -->
+<h3 id="Query">Constructing the query</h3>
+<p>
+ The next step in retrieving data a provider is to construct a query. This first snippet
+ defines some variables for accessing the User Dictionary Provider:
+</p>
+<pre class="prettyprint">
+
+// A "projection" defines the columns that will be returned for each row
+String[] mProjection =
+{
+ UserDictionary.Words._ID, // Contract class constant for the _ID column name
+ UserDictionary.Words.WORD, // Contract class constant for the word column name
+ UserDictionary.Words.LOCALE // Contract class constant for the locale column name
+};
+
+// Defines a string to contain the selection clause
+String mSelectionClause = null;
+
+// Initializes an array to contain selection arguments
+String[] mSelectionArgs = {""};
+
+</pre>
+<p>
+ The next snippet shows how to use
+ {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ ContentResolver.query()}, using the User Dictionary Provider as an example.
+ A provider client query is similar to an SQL query, and it contains a set of columns to return,
+ a set of selection criteria, and a sort order.
+</p>
+<p>
+ The set of columns that the query should return is called a <strong>projection</strong>
+ (the variable <code>mProjection</code>).
+</p>
+<p>
+ The expression that specifies the rows to retrieve is split into a selection clause and
+ selection arguments. The selection clause is a combination of logical and Boolean expressions,
+ column names, and values (the variable <code>mSelection</code>). If you specify the replaceable
+ parameter <code>?</code> instead of a value, the query method retrieves the value from the
+ selection arguments array (the variable <code>mSelectionArgs</code>).
+</p>
+<p>
+ In the next snippet, if the user doesn't enter a word, the selection clause is set to
+ <code>null</code>, and the query returns all the words in the provider. If the user enters
+ a word, the selection clause is set to <code>UserDictionary.Words.Word + " = ?"</code> and
+ the first element of selection arguments array is set to the word the user enters.
+</p>
+<pre class="prettyprint">
+/*
+ * This defines a one-element String array to contain the selection argument.
+ */
+String[] mSelectionArgs = {""};
+
+// Gets a word from the UI
+mSearchString = mSearchWord.getText().toString();
+
+// Remember to insert code here to check for invalid or malicious input.
+
+// If the word is the empty string, gets everything
+if (TextUtils.isEmpty(mSearchString)) {
+ // Setting the selection clause to null will return all words
+ mSelectionClause = null;
+ mSelectionArgs[0] = "";
+
+} else {
+ // Constructs a selection clause that matches the word that the user entered.
+ mSelectionClause = " = ?";
+
+ // Moves the user's input string to the selection arguments.
+ mSelectionArgs[0] = mSearchString;
+
+}
+
+// Does a query against the table and returns a Cursor object
+mCursor = getContentResolver().query(
+ UserDictionary.Words.CONTENT_URI, // The content URI of the words table
+ mProjection, // The columns to return for each row
+ mSelectionClause // Either null, or the word the user entered
+ mSelectionArgs, // Either empty, or the string the user entered
+ mSortOrder); // The sort order for the returned rows
+
+// Some providers return null if an error occurs, others throw an exception
+if (null == mCursor) {
+ /*
+ * Insert code here to handle the error. Be sure not to use the cursor! You may want to
+ * call android.util.Log.e() to log this error.
+ *
+ */
+// If the Cursor is empty, the provider found no matches
+} else if (mCursor.getCount() < 1) {
+
+ /*
+ * Insert code here to notify the user that the search was unsuccessful. This isn't necessarily
+ * an error. You may want to offer the user the option to insert a new row, or re-type the
+ * search term.
+ */
+
+} else {
+ // Insert code here to do something with the results
+
+}
+</pre>
+<p>
+ This query is analogous to the SQL statement:
+</p>
+<pre>
+SELECT _ID, word, frequency, locale FROM words WHERE word = <userinput> ORDER BY word ASC;
+</pre>
+<p>
+ In this SQL statement, the actual column names are used instead of contract class constants.
+</p>
+<h4 id="Injection">Protecting against malicious input</h4>
+<p>
+ If the data managed by the content provider is in an SQL database, including external untrusted
+ data into raw SQL statements can lead to SQL injection.
+</p>
+<p>
+ Consider this selection clause:
+</p>
+<pre>
+// Constructs a selection clause by concatenating the user's input to the column name
+String mSelectionClause = "var = " + mUserInput;
+</pre>
+<p>
+ If you do this, you're allowing the user to concatenate malicious SQL onto your SQL statement.
+ For example, the user could enter "nothing; DROP TABLE *;" for <code>mUserInput</code>, which
+ would result in the selection clause <code>var = nothing; DROP TABLE *;</code>. Since the
+ selection clause is treated as an SQL statement, this might cause the provider to erase all of
+ the tables in the underlying SQLite database (unless the provider is set up to catch
+ <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL injection</a> attempts).
+</p>
+<p>
+ To avoid this problem, use a selection clause that uses <code>?</code> as a replaceable
+ parameter and a separate array of selection arguments. When you do this, the user input
+ is bound directly to the query rather than being interpreted as part of an SQL statement.
+ Because it's not treated as SQL, the user input can't inject malicious SQL. Instead of using
+ concatenation to include the user input, use this selection clause:
+</p>
+<pre>
+// Constructs a selection clause with a replaceable parameter
+String mSelectionClause = "var = ?";
+</pre>
+<p>
+ Set up the array of selection arguments like this:
+</p>
+<pre>
+// Defines an array to contain the selection arguments
+String[] selectionArgs = {""};
+</pre>
+<p>
+ Put a value in the selection arguments array like this:
+</p>
+<pre>
+// Sets the selection argument to the user's input
+selectionArgs[0] = mUserInput;
+</pre>
+<p>
+ A selection clause that uses <code>?</code> as a replaceable parameter and an array of
+ selection arguments array are preferred way to specify a selection, even the provider isn't
+ based on an SQL database.
+</p>
+<!-- Displaying the results -->
+<h3 id="DisplayResults">Displaying query results</h3>
+<p>
+ The {@link android.content.ContentResolver#query(Uri, String[], String, String[], String)
+ ContentResolver.query()} client method always returns a {@link android.database.Cursor}
+ containing the columns specified by the query's projection for the rows that match the query's
+ selection criteria. A {@link android.database.Cursor} object provides random read access to the
+ rows and columns it contains. Using {@link android.database.Cursor} methods,
+ you can iterate over the rows in the results, determine the data type of each column, get the
+ data out of a column, and examine other properties of the results. Some
+ {@link android.database.Cursor} implementations automatically update the object when the
+ provider's data changes, or trigger methods in an observer object when the
+ {@link android.database.Cursor} changes, or both.
+</p>
+<p class="note">
+ <strong>Note:</strong> A provider may restrict access to columns based on the nature of the
+ object making the query. For example, the Contacts Provider restricts access for some columns to
+ sync adapters, so it won't return them to an activity or service.
+</p>
+<p>
+ If no rows match the selection criteria, the provider
+ returns a {@link android.database.Cursor} object for which
+ {@link android.database.Cursor#getCount() Cursor.getCount()} is 0 (an empty cursor).
+</p>
+<p>
+ If an internal error occurs, the results of the query depend on the particular provider. It may
+ choose to return <code>null</code>, or it may throw an {@link java.lang.Exception}.
+</p>
+<p>
+ Since a {@link android.database.Cursor} is a "list" of rows, a good way to display the
+ contents of a {@link android.database.Cursor} is to link it to a {@link android.widget.ListView}
+ via a {@link android.widget.SimpleCursorAdapter}.
+</p>
+<p>
+ The following snippet continues the code from the previous snippet. It creates a
+ {@link android.widget.SimpleCursorAdapter} object containing the {@link android.database.Cursor}
+ retrieved by the query, and sets this object to be the adapter for a
+ {@link android.widget.ListView}:
+</p>
+<pre class="prettyprint">
+// Defines a list of columns to retrieve from the Cursor and load into an output row
+String[] mWordListColumns =
+{
+ UserDictionary.Words.WORD, // Contract class constant containing the word column name
+ UserDictionary.Words.LOCALE // Contract class constant containing the locale column name
+};
+
+// Defines a list of View IDs that will receive the Cursor columns for each row
+int[] mWordListItems = { R.id.dictWord, R.id.locale};
+
+// Creates a new SimpleCursorAdapter
+mCursorAdapter = new SimpleCursorAdapter(
+ getApplicationContext(), // The application's Context object
+ R.layout.wordlistrow, // A layout in XML for one row in the ListView
+ mCursor, // The result from the query
+ mWordListColumns, // A string array of column names in the cursor
+ mWordListItems, // An integer array of view IDs in the row layout
+ 0); // Flags (usually none are needed)
+
+// Sets the adapter for the ListView
+mWordList.setAdapter(mCursorAdapter);
+</pre>
+<p class="note">
+ <strong>Note:</strong> To back a {@link android.widget.ListView} with a
+ {@link android.database.Cursor}, the cursor must contain a column named <code>_ID</code>.
+ Because of this, the query shown previously retrieves the <code>_ID</code> column for the
+ "words" table, even though the {@link android.widget.ListView} doesn't display it.
+ This restriction also explains why most providers have a <code>_ID</code> column for each of
+ their tables.
+</p>
+
+ <!-- Getting data from query results -->
+<h3 id="GettingResults">Getting data from query results</h3>
+<p>
+ Rather than simply displaying query results, you can use them for other tasks. For
+ example, you can retrieve spellings from the user dictionary and then look them up in
+ other providers. To do this, you iterate over the rows in the {@link android.database.Cursor}:
+</p>
+<pre class="prettyprint">
+
+// Determine the column index of the column named "word"
+int index = mCursor.getColumnIndex(UserDictionary.Words.WORD);
+
+/*
+ * Only executes if the cursor is valid. The User Dictionary Provider returns null if
+ * an internal error occurs. Other providers may throw an Exception instead of returning null.
+ */
+
+if (mCursor != null) {
+ /*
+ * Moves to the next row in the cursor. Before the first movement in the cursor, the
+ * "row pointer" is -1, and if you try to retrieve data at that position you will get an
+ * exception.
+ */
+ while (mCursor.moveToNext()) {
+
+ // Gets the value from the column.
+ newWord = mCursor.getString(index);
+
+ // Insert code here to process the retrieved word.
+
+ ...
+
+ // end of while loop
+ }
+} else {
+
+ // Insert code here to report an error if the cursor is null or the provider threw an exception.
+}
+</pre>
+<p>
+ {@link android.database.Cursor} implementations contain several "get" methods for
+ retrieving different types of data from the object. For example, the previous snippet
+ uses {@link android.database.Cursor#getString(int) getString()}. They also have a
+ {@link android.database.Cursor#getType(int) getType()} method that returns a value indicating
+ the data type of the column.
+</p>
+
+
+ <!-- Requesting permissions -->
+<h2 id="Permissions">Content Provider Permissions</h2>
+<p>
+ A provider's application can specify permissions that other applications must have in order to
+ access the provider's data. These permissions ensure that the user knows what data
+ an application will try to access. Based on the provider's requirements, other applications
+ request the permissions they need in order to access the provider. End users see the requested
+ permissions when they install the application.
+</p>
+<p>
+ If a provider's application doesn't specify any permissions, then other applications have no
+ access to the provider's data. However, components in the provider's application always have
+ full read and write access, regardless of the specified permissions.
+</p>
+<p>
+ As noted previously, the User Dictionary Provider requires the
+ <code>android.permission.READ_USER_DICTIONARY</code> permission to retrieve data from it.
+ The provider has the separate <code>android.permission.WRITE_USER_DICTIONARY</code>
+ permission for inserting, updating, or deleting data.
+</p>
+<p>
+ To get the permissions needed to access a provider, an application requests them with a
+ <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">
+ <uses-permission></a></code> element in its manifest file.
+ When the Android Package Manager installs the application, a user must approve all of the
+ permissions the application requests. If the user approves all of them, Package Manager
+ continues the installation; if the user doesn't approve them, Package Manager
+ aborts the installation.
+</p>
+<p>
+ The following
+ <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">
+ <uses-permission></a></code> element requests read access to the User Dictionary Provider:
+</p>
+<pre>
+ <uses-permission android:name="android.permission.READ_USER_DICTIONARY">
+</pre>
+<p>
+ The impact of permissions on provider access is explained in more detail in the
+ <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> guide.
+</p>
+
+
+<!-- Inserting, Updating, and Deleting Data -->
+<h2 id="Modifications">Inserting, Updating, and Deleting Data</h2>
+<p>
+ In the same way that you retrieve data from a provider, you also use the interaction between
+ a provider client and the provider's {@link android.content.ContentProvider} to modify data.
+ You call a method of {@link android.content.ContentResolver} with arguments that are passed to
+ the corresponding method of {@link android.content.ContentProvider}. The provider and provider
+ client automatically handle security and inter-process communication.
+</p>
+<h3 id="Inserting">Inserting data</h3>
+<p>
+ To insert data into a provider, you call the
+ {@link android.content.ContentResolver#insert(Uri,ContentValues) ContentResolver.insert()}
+ method. This method inserts a new row into the provider and returns a content URI for that row.
+ This snippet shows how to insert a new word into the User Dictionary Provider:
+</p>
+<pre class="prettyprint">
+// Defines a new Uri object that receives the result of the insertion
+Uri mNewUri;
+
+...
+
+// Defines an object to contain the new values to insert
+ContentValues mNewValues = new ContentValues();
+
+/*
+ * Sets the values of each column and inserts the word. The arguments to the "put"
+ * method are "column name" and "value"
+ */
+mNewValues.put(UserDictionary.Words.APP_ID, "example.user");
+mNewValues.put(UserDictionary.Words.LOCALE, "en_US");
+mNewValues.put(UserDictionary.Words.WORD, "insert");
+mNewValues.put(UserDictionary.Words.FREQUENCY, "100");
+
+mNewUri = getContentResolver().insert(
+ UserDictionary.Word.CONTENT_URI, // the user dictionary content URI
+ mNewValues // the values to insert
+);
+</pre>
+<p>
+ The data for the new row goes into a single {@link android.content.ContentValues} object, which
+ is similar in form to a one-row cursor. The columns in this object don't need to have the
+ same data type, and if you don't want to specify a value at all, you can set a column
+ to <code>null</code> using {@link android.content.ContentValues#putNull(String)
+ ContentValues.putNull()}.
+</p>
+<p>
+ The snippet doesn't add the <code>_ID</code> column, because this column is maintained
+ automatically. The provider assigns a unique value of <code>_ID</code> to every row that is
+ added. Providers usually use this value as the table's primary key.
+</p>
+<p>
+ The content URI returned in <code>newUri</code> identifies the newly-added row, with
+ the following format:
+</p>
+<pre>
+content://user_dictionary/words/<id_value>
+</pre>
+<p>
+ The <code><id_value></code> is the contents of <code>_ID</code> for the new row.
+ Most providers can detect this form of content URI automatically and then perform the requested
+ operation on that particular row.
+</p>
+<p>
+ To get the value of <code>_ID</code> from the returned {@link android.net.Uri}, call
+ {@link android.content.ContentUris#parseId(Uri) ContentUris.parseId()}.
+</p>
+<h3 id="Updating">Updating data</h3>
+<p>
+ To update a row, you use a {@link android.content.ContentValues} object with the updated
+ values just as you do with an insertion, and selection criteria just as you do with a query.
+ The client method you use is
+ {@link android.content.ContentResolver#update(Uri, ContentValues, String, String[])
+ ContentResolver.update()}. You only need to add values to the
+ {@link android.content.ContentValues} object for columns you're updating. If you want to clear
+ the contents of a column, set the value to <code>null</code>.
+</p>
+<p>
+ The following snippet changes all the rows whose locale has the language "en" to a
+ have a locale of <code>null</code>. The return value is the number of rows that were updated:
+</p>
+<pre>
+// Defines an object to contain the updated values
+ContentValues mUpdateValues = new ContentValues();
+
+// Defines selection criteria for the rows you want to update
+String mSelectionClause = UserDictionary.Words.LOCALE + "LIKE ?";
+String[] mSelectionArgs = {"en_%"};
+
+// Defines a variable to contain the number of updated rows
+int mRowsUpdated = 0;
+
+...
+
+/*
+ * Sets the updated value and updates the selected words.
+ */
+mUpdateValues.putNull(UserDictionary.Words.LOCALE);
+
+mRowsUpdated = getContentResolver().update(
+ UserDictionary.Words.CONTENT_URI, // the user dictionary content URI
+ mUpdateValues // the columns to update
+ mSelectionClause // the column to select on
+ mSelectionArgs // the value to compare to
+);
+</pre>
+<p>
+ You should also sanitize user input when you call
+ {@link android.content.ContentResolver#update(Uri, ContentValues, String, String[])
+ ContentResolver.update()}. To learn more about this, read the section
+ <a href="#Injection">Protecting against malicious input</a>.
+</p>
+<h3 id="Deleting">Deleting data</h3>
+<p>
+ Deleting rows is similar to retrieving row data: you specify selection criteria for the rows
+ you want to delete and the client method returns the number of deleted rows.
+ The following snippet deletes rows whose appid matches "user". The method returns the
+ number of deleted rows.
+</p>
+<pre>
+
+// Defines selection criteria for the rows you want to delete
+String mSelectionClause = UserDictionary.Words.APP_ID + " LIKE ?";
+String[] mSelectionArgs = {"user"};
+
+// Defines a variable to contain the number of rows deleted
+int mRowsDeleted = 0;
+
+...
+
+// Deletes the words that match the selection criteria
+mRowsDeleted = getContentResolver().delete(
+ UserDictionary.Words.CONTENT_URI, // the user dictionary content URI
+ mSelectionClause // the column to select on
+ mSelectionArgs // the value to compare to
+);
+</pre>
+<p>
+ You should also sanitize user input when you call
+ {@link android.content.ContentResolver#delete(Uri, String, String[])
+ ContentResolver.delete()}. To learn more about this, read the section
+ <a href="#Injection">Protecting against malicious input</a>.
+</p>
+<!-- Provider Data Types -->
+<h2 id="DataTypes">Provider Data Types</h2>
+<p>
+ Content providers can offer many different data types. The User Dictionary Provider offers only
+ text, but providers can also offer the following formats:
+</p>
+ <ul>
+ <li>
+ integer
+ </li>
+ <li>
+ long integer (long)
+ </li>
+ <li>
+ floating point
+ </li>
+ <li>
+ long floating point (double)
+ </li>
+ </ul>
+<p>
+ Another data type that providers often use is Binary Large OBject (BLOB) implemented as a
+ 64KB byte array. You can see the available data types by looking at the
+ {@link android.database.Cursor} class "get" methods.
+</p>
+<p>
+ The data type for each column in a provider is usually listed in its documentation.
+ The data types for the User Dictionary Provider are listed in the reference documentation
+ for its contract class {@link android.provider.UserDictionary.Words} (contract classes are
+ described in the section <a href="#ContractClasses">Contract Classes</a>).
+ You can also determine the data type by calling {@link android.database.Cursor#getType(int)
+ Cursor.getType()}.
+</p>
+<p>
+ Providers also maintain MIME data type information for each content URI they define. You can
+ use the MIME type information to find out if your application can handle data that the
+ provider offers, or to choose a type of handling based on the MIME type. You usually need the
+ MIME type when you are working with a provider that contains complex
+ data structures or files. For example, the {@link android.provider.ContactsContract.Data}
+ table in the Contacts Provider uses MIME types to label the type of contact data stored in each
+ row. To get the MIME type corresponding to a content URI, call
+ {@link android.content.ContentResolver#getType(Uri) ContentResolver.getType()}.
+</p>
+<p>
+ The section <a href="#MIMETypeReference">MIME Type Reference</a> describes the
+ syntax of both standard and custom MIME types.
+</p>
+
+
+<!-- Alternative Forms of Provider Access -->
+<h2 id="AltForms">Alternative Forms of Provider Access</h2>
+<p>
+ Three alternative forms of provider access are important in application development:
+</p>
+<ul>
+ <li>
+ <a href="#Batch">Batch access</a>: You can create a batch of access calls with methods in
+ the {@link android.content.ContentProviderOperation} class, and then apply them with
+ {@link android.content.ContentResolver#applyBatch(String, ArrayList)
+ ContentResolver.applyBatch()}.
+ </li>
+ <li>
+ Asynchronous queries: You should do queries in a separate thread. One way to do this is to
+ use a {@link android.content.CursorLoader} object. The examples in the
+ <a href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a> guide demonstrate
+ how to do this.
+ </li>
+ <li>
+ <a href="#Intents">Data access via intents</a>: Although you can't send an intent
+ directly to a provider, you can send an intent to the provider's application, which is
+ usually the best-equipped to modify the provider's data.
+ </li>
+</ul>
+<p>
+ Batch access and modification via intents are described in the following sections.
+</p>
+<h3 id="Batch">Batch access</h3>
+<p>
+ Batch access to a provider is useful for inserting a large number of rows, or for inserting
+ rows in multiple tables in the same method call, or in general for performing a set of
+ operations across process boundaries as a transaction (an atomic operation).
+</p>
+<p>
+ To access a provider in "batch mode",
+ you create an array of {@link android.content.ContentProviderOperation} objects and then
+ dispatch them to a content provider with
+ {@link android.content.ContentResolver#applyBatch(String, ArrayList)
+ ContentResolver.applyBatch()}. You pass the content provider's <em>authority</em> to this
+ method, rather than a particular content URI, which allows each
+ {@link android.content.ContentProviderOperation} object in the array to work against a
+ different table. A call to {@link android.content.ContentResolver#applyBatch(String, ArrayList)
+ ContentResolver.applyBatch()} returns an array of results.
+</p>
+<p>
+ The description of the {@link android.provider.ContactsContract.RawContacts} contract class
+ includes a code snippet that demonstrates batch insertion. The
+ <a href="{@docRoot}resources/samples/ContactManager/index.html">Contact Manager</a>
+ sample application contains an example of batch access in its <code>ContactAdder.java</code>
+ source file.
+</p>
+<div class="sidebox-wrapper">
+<div class="sidebox">
+<h2>Displaying data using a helper app</h2>
+<p>
+ If your application <em>does</em> have access permissions, you still may want to use an
+ intent to display data in another application. For example, the Calendar application accepts an
+ {@link android.content.Intent#ACTION_VIEW} intent, which displays a particular date or event.
+ This allows you to display calendar information without having to create your own UI.
+ To learn more about this feature, see the
+ <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a> guide.
+</p>
+<p>
+ The application to which you send the intent doesn't have to be the application
+ associated with the provider. For example, you can retrieve a contact from the
+ Contact Provider, then send an {@link android.content.Intent#ACTION_VIEW} intent
+ containing the content URI for the contact's image to an image viewer.
+</p>
+</div>
+</div>
+<h3 id="Intents">Data access via intents</h3>
+<p>
+ Intents can provide indirect access to a content provider. You allow the user to access
+ data in a provider even if your application doesn't have access permissions, either by
+ getting a result intent back from an application that has permissions, or by activating an
+ application that has permissions and letting the user do work in it.
+</p>
+<h4>Getting access with temporary permissions</h4>
+<p>
+ You can access data in a content provider, even if you don't have the proper access
+ permissions, by sending an intent to an application that does have the permissions and
+ receiving back a result intent containing "URI" permissions.
+ These are permissions for a specific content URI that last until the activity that receives
+ them is finished. The application that has permanent permissions grants temporary
+ permissions by setting a flag in the result intent:
+</p>
+<ul>
+ <li>
+ <strong>Read permission:</strong>
+ {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}
+ </li>
+ <li>
+ <strong>Write permission:</strong>
+ {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}
+ </li>
+</ul>
+<p class="note">
+ <strong>Note:</strong> These flags don't give general read or write access to the provider
+ whose authority is contained in the content URI. The access is only for the URI itself.
+</p>
+<p>
+ A provider defines URI permissions for content URIs in its manifest, using the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
+ android:grantUriPermission</a></code>
+ attribute of the
+ {@code <a href="guide/topics/manifest/provider-element.html"><provider></a>}
+ element, as well as the
+ {@code <a href="guide/topics/manifest/grant-uri-permission-element.html">
+ <grant-uri-permission></a>} child element of the
+ {@code <a href="guide/topics/manifest/provider-element.html"><provider></a>}
+ element. The URI permissions mechanism is explained in more detail in the
+ <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> guide,
+ in the section "URI Permissions".
+</p>
+<p>
+ For example, you can retrieve data for a contact in the Contacts Provider, even if you don't
+ have the {@link android.Manifest.permission#READ_CONTACTS} permission. You might want to do
+ this in an application that sends e-greetings to a contact on his or her birthday. Instead of
+ requesting {@link android.Manifest.permission#READ_CONTACTS}, which gives you access to all of
+ the user's contacts and all of their information, you prefer to let the user control which
+ contacts are used by your application. To do this, you use the following process:
+</p>
+<ol>
+ <li>
+ Your application sends an intent containing the action
+ {@link android.content.Intent#ACTION_PICK} and the "contacts" MIME type
+ {@link android.provider.ContactsContract.RawContacts#CONTENT_ITEM_TYPE}, using the
+ method {@link android.app.Activity#startActivityForResult(Intent, int)
+ startActivityForResult()}.
+ </li>
+ <li>
+ Because this intent matches the intent filter for the
+ People app's "selection" activity, the activity will come to the foreground.
+ </li>
+ <li>
+ In the selection activity, the user selects a
+ contact to update. When this happens, the selection activity calls
+ {@link android.app.Activity#setResult(int, Intent) setResult(resultcode, intent)}
+ to set up a intent to give back to your application. The intent contains the content URI
+ of the contact the user selected, and the "extras" flags
+ {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}. These flags grant URI
+ permission to your app to read data for the contact pointed to by the
+ content URI. The selection activity then calls {@link android.app.Activity#finish()} to
+ return control to your application.
+ </li>
+ <li>
+ Your activity returns to the foreground, and the system calls your activity's
+ {@link android.app.Activity#onActivityResult(int, int, Intent) onActivityResult()}
+ method. This method receives the result intent created by the selection activity in
+ the People app.
+ </li>
+ <li>
+ With the content URI from the result intent, you can read the contact's data
+ from the Contacts Provider, even though you didn't request permanent read access permission
+ to the provider in your manifest. You can then get the contact's birthday information
+ or his or her email address and then send the e-greeting.
+ </li>
+</ol>
+<h4>Using another application</h4>
+<p>
+ A simple way to allow the user to modify data to which you don't have access permissions is to
+ activate an application that has permissions and let the user do the work there.
+</p>
+<p>
+ For example, the Calendar application accepts an
+ {@link android.content.Intent#ACTION_INSERT} intent, which allows you to activate the
+ application's insert UI. You can pass "extras" data in this intent, which the application
+ uses to pre-populate the UI. Because recurring events have a complex syntax, the preferred
+ way of inserting events into the Calendar Provider is to activate the Calendar app with an
+ {@link android.content.Intent#ACTION_INSERT} and then let the user insert the event there.
+</p>
+<!-- Contract Classes -->
+<h2 id="ContractClasses">Contract Classes</h2>
+<p>
+ A contract class defines constants that help applications work with the content URIs, column
+ names, intent actions, and other features of a content provider. Contract classes are not
+ included automatically with a provider; the provider's developer has to define them and then
+ make them available to other developers. Many of the providers included with the Android
+ platform have corresponding contract classes in the package {@link android.provider}.
+</p>
+<p>
+ For example, the User Dictionary Provider has a contract class
+ {@link android.provider.UserDictionary} containing content URI and column name constants. The
+ content URI for the "words" table is defined in the constant
+ {@link android.provider.UserDictionary.Words#CONTENT_URI UserDictionary.Words.CONTENT_URI}.
+ The {@link android.provider.UserDictionary.Words} class also contains column name constants,
+ which are used in the example snippets in this guide. For example, a query projection can be
+ defined as:
+</p>
+<pre>
+String[] mProjection =
+{
+ UserDictionary.Words._ID,
+ UserDictionary.Words.WORD,
+ UserDictionary.Words.LOCALE
+};
+</pre>
+<p>
+ Another contract class is {@link android.provider.ContactsContract} for the Contacts Provider.
+ The reference documentation for this class includes example code snippets. One of its
+ subclasses, {@link android.provider.ContactsContract.Intents.Insert}, is a contract
+ class that contains constants for intents and intent data.
+</p>
+
+
+<!-- MIME Type Reference -->
+<h2 id="MIMETypeReference">MIME Type Reference</h2>
+<p>
+ Content providers can return standard MIME media types, or custom MIME type strings, or both.
+</p>
+<p>
+ MIME types have the format
+</p>
+<pre>
+<em>type</em>/<em>subtype</em>
+</pre>
+<p>
+ For example, the well-known MIME type <code>text/html</code> has the <code>text</code> type and
+ the <code>html</code> subtype. If the provider returns this type for a URI, it means that a
+ query using that URI will return text containing HTML tags.
+</p>
+<p>
+ Custom MIME type strings, also called "vendor-specific" MIME types, have more
+ complex <em>type</em> and <em>subtype</em> values. The <em>type</em> value is always
+</p>
+<pre>
+vnd.android.cursor.<strong>dir</strong>
+</pre>
+<p>
+ for multiple rows, or
+</p>
+<pre>
+vnd.android.cursor.<strong>item</strong>
+</pre>
+<p>
+ for a single row.
+</p>
+<p>
+ The <em>subtype</em> is provider-specific. The Android built-in providers usually have a simple
+ subtype. For example, the when the Contacts application creates a row for a telephone number,
+ it sets the following MIME type in the row:
+</p>
+<pre>
+vnd.android.cursor.item/phone_v2
+</pre>
+<p>
+ Notice that the subtype value is simply <code>phone_v2</code>.
+</p>
+<p>
+ Other provider developers may create their own pattern of subtypes based on the provider's
+ authority and table names. For example, consider a provider that contains train timetables.
+ The provider's authority is <code>com.example.trains</code>, and it contains the tables
+ Line1, Line2, and Line3. In response to the content URI
+</p>
+<p>
+<pre>
+content://com.example.trains/Line1
+</pre>
+<p>
+ for table Line1, the provider returns the MIME type
+</p>
+<pre>
+vnd.android.cursor.<strong>dir</strong>/vnd.example.line1
+</pre>
+<p>
+ In response to the content URI
+</p>
+<pre>
+content://com.example.trains/Line2/5
+</pre>
+<p>
+ for row 5 in table Line2, the provider returns the MIME type
+</p>
+<pre>
+vnd.android.cursor.<strong>item</strong>/vnd.example.line2
+</pre>
+<p>
+ Most content providers define contract class constants for the MIME types they use. The
+ Contacts Provider contract class {@link android.provider.ContactsContract.RawContacts},
+ for example, defines the constant
+ {@link android.provider.ContactsContract.RawContacts#CONTENT_ITEM_TYPE} for the MIME type of
+ a single raw contact row.
+</p>
+<p>
+ Content URIs for single rows are described in the section
+ <a href="#ContentURIs">Content URIs</a>.
+</p>
diff --git a/docs/html/guide/topics/providers/content-provider-creating.jd b/docs/html/guide/topics/providers/content-provider-creating.jd
new file mode 100644
index 0000000..4ebdb50
--- /dev/null
+++ b/docs/html/guide/topics/providers/content-provider-creating.jd
@@ -0,0 +1,1215 @@
+page.title=Creating a Content Provider
+@jd:body
+<div id="qv-wrapper">
+<div id="qv">
+
+
+<h2>In this document</h2>
+<ol>
+ <li>
+ <a href="#DataStorage">Designing Data Storage</a>
+ </li>
+ <li>
+ <a href="#ContentURI">Designing Content URIs</a>
+ </li>
+ <li>
+ <a href="#ContentProvider">Implementing the ContentProvider Class</a>
+ <ol>
+ <li>
+ <a href="#RequiredAccess">Required Methods</a>
+ </li>
+ <li>
+ <a href="#Query">Implementing the query() method</a>
+ </li>
+ <li>
+ <a href="#Insert">Implementing the insert() method</a>
+ </li>
+ <li>
+ <a href="#Delete">Implementing the delete() method</a>
+ </li>
+ <li>
+ <a href="#Update">Implementing the update() method</a>
+ </li>
+ <li>
+ <a href="#OnCreate">Implementing the onCreate() method</a>
+ </li>
+ </ol>
+ </li>
+ <li>
+ <a href="#MIMETypes">Implementing Content Provider MIME Types</a>
+ <ol>
+ <li>
+ <a href="#TableMIMETypes">MIME types for tables</a>
+ </li>
+ <li>
+ <a href="#FileMIMETypes">MIME types for files</a>
+ </li>
+ </ol>
+ </li>
+ <li>
+ <a href="#ContractClass">Implementing a Contract Class</a>
+ </li>
+ <li>
+ <a href="#Permissions">Implementing Content Provider Permissions</a>
+ </li>
+ <li>
+ <a href="#ProviderElement">The <provider> Element</a>
+ </li>
+ <li>
+ <a href="#Intents">Intents and Data Access</a>
+ </li>
+</ol>
+<h2>Key classes</h2>
+ <ol>
+ <li>
+ {@link android.content.ContentProvider}
+ </li>
+ <li>
+ {@link android.database.Cursor}
+ </li>
+ <li>
+ {@link android.net.Uri}
+ </li>
+ </ol>
+<h2>Related Samples</h2>
+ <ol>
+ <li>
+ <a
+ href="{@docRoot}resources/samples/NotePad/index.html">
+ Note Pad sample application
+ </a>
+ </li>
+ </ol>
+<h2>See also</h2>
+ <ol>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
+ Content Provider Basics</a>
+ </li>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/calendar-provider.html">
+ Calendar Provider</a>
+ </li>
+ </ol>
+</div>
+</div>
+
+
+<p>
+ A content provider manages access to a central repository of data. You implement a
+ provider as one or more classes in an Android application, along with elements in
+ the manifest file. One of your classes implements a subclass
+ {@link android.content.ContentProvider}, which is the interface between your provider and
+ other applications. Although content providers are meant to make data available to other
+ applications, you may of course have activities in your application that allow the user
+ to query and modify the data managed by your provider.
+</p>
+<p>
+ The rest of this topic is a basic list of steps for building a content provider and a list
+ of APIs to use.
+</p>
+
+
+<!-- Before You Start Building -->
+<h2 id="BeforeYouStart">Before You Start Building</h2>
+<p>
+ Before you start building a provider, do the following:
+</p>
+<ol>
+ <li>
+ <strong>Decide if you need a content provider</strong>. You need to build a content
+ provider if you want to provide one or more of the following features:
+ <ul>
+ <li>You want to offer complex data or files to other applications.</li>
+ <li>You want to allow users to copy complex data from your app into other apps.</li>
+ <li>You want to provide custom search suggestions using the search framework.</li>
+ </ul>
+ <p>
+ You <em>don't</em> need a provider to use an SQLite database if the use is entirely within
+ your own application.
+ </p>
+ </li>
+ <li>
+ If you haven't done so already, read the topic
+ <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
+ Content Provider Basics</a> to learn more about providers.
+ </li>
+</ol>
+<p>
+ Next, follow these steps to build your provider:
+</p>
+<ol>
+ <li>
+ Design the raw storage for your data. A content provider offers data in two ways:
+ <dl>
+ <dt>
+ File data
+ </dt>
+ <dd>
+ Data that normally goes into files, such as
+ photos, audio, or videos. Store the files in your application's private
+ space. In response to a request for a file from another application, your
+ provider can offer a handle to the file.
+ </dd>
+ <dt>
+ "Structured" data
+ </dt>
+ <dd>
+ Data that normally goes into a database, array, or similar structure.
+ Store the data in a form that's compatible with tables of rows and columns. A row
+ represents an entity, such as a person or an item in inventory. A column represents
+ some data for the entity, such a person's name or an item's price. A common way to
+ store this type of data is in an SQLite database, but you can use any type of
+ persistent storage. To learn more about the storage types available in the
+ Android system, see the section <a href="#DataStorage">
+ Designing Data Storage</a>.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ Define a concrete implementation of the {@link android.content.ContentProvider} class and
+ its required methods. This class is the interface between your data and the rest of the
+ Android system. For more information about this class, see the section
+ <a href="#ContentProvider">Implementing the ContentProvider Class</a>.
+ </li>
+ <li>
+ Define the provider's authority string, its content URIs, and column names. If you want
+ the provider's application to handle intents, also define intent actions, extras data,
+ and flags. Also define the permissions that you will require for applications that want
+ to access your data. You should consider defining all of these values as constants in a
+ separate contract class; later, you can expose this class to other developers. For more
+ information about content URIs, see the
+ section <a href="#ContentURI">Designing Content URIs</a>.
+ For more information about intents, see the
+ section <a href="#Intents">Intents and Data Access</a>.
+ </li>
+ <li>
+ Add other optional pieces, such as sample data or an implementation
+ of {@link android.content.AbstractThreadedSyncAdapter} that can synchronize data between
+ the provider and cloud-based data.
+ </li>
+</ol>
+
+
+<!-- Designing Data Storage -->
+<h2 id="DataStorage">Designing Data Storage</h2>
+<p>
+ A content provider is the interface to data saved in a structured format. Before you create
+ the interface, you must decide how to store the data. You can store the data in any form you
+ like, and then design the interface to read and write the data as necessary.
+</p>
+<p>
+ These are some of the data storage technologies that are available in Android:
+</p>
+<ul>
+ <li>
+ The Android system includes an SQLite database API that Android's own providers use
+ to store table-oriented data. The
+ {@link android.database.sqlite.SQLiteOpenHelper} class helps you create databases, and the
+ {@link android.database.sqlite.SQLiteDatabase} class is the base class for accessing
+ databases.
+ <p>
+ Remember that you don't have to use a database to implement your repository. A provider
+ appears externally as a set of tables, similar to a relational database, but this is
+ not a requirement for the provider's internal implementation.
+ </p>
+ </li>
+ <li>
+ For storing file data, Android has a variety of file-oriented APIs.
+ To learn more about file storage, read the topic
+ <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a>. If you're
+ designing a provider that offers media-related data such as music or videos, you can
+ have a provider that combines table data and files.
+ </li>
+ <li>
+ For working with network-based data, use classes in {@link java.net} and
+ {@link android.net}. You can also synchronize network-based data to a local data
+ store such as a database, and then offer the data as tables or files.
+ The <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">
+ Sample Sync Adapter</a> sample application demonstrates this type of synchronization.
+ </li>
+</ul>
+<h3 id="DataDesign">
+ Data design considerations
+</h3>
+<p>
+ Here are some tips for designing your provider's data structure:
+</p>
+<ul>
+ <li>
+ Table data should always have a "primary key" column that the provider maintains
+ as a unique numeric value for each row. You can use this value to link the row to related
+ rows in other tables (using it as a "foreign key"). Although you can use any name
+ for this column, using {@link android.provider.BaseColumns#_ID BaseColumns._ID} is the best
+ choice, because linking the results of a provider query to a
+ {@link android.widget.ListView} requires one of the retrieved columns to have the name
+ <code>_ID</code>.
+ </li>
+ <li>
+ If you want to provide bitmap images or other very large pieces of file-oriented data, store
+ the data in a file and then provide it indirectly rather than storing it directly in a
+ table. If you do this, you need to tell users of your provider that they need to use a
+ {@link android.content.ContentResolver} file method to access the data.
+ </li>
+ <li>
+ Use the Binary Large OBject (BLOB) data type to store data that varies in size or has a
+ varying structure. For example, you can use a BLOB column to store a
+ <a href="http://code.google.com/p/protobuf">protocol buffer</a> or
+ <a href="http://www.json.org">JSON structure</a>.
+ <p>
+ You can also use a BLOB to implement a <em>schema-independent</em> table. In
+ this type of table, you define a primary key column, a MIME type column, and one or
+ more generic columns as BLOB. The meaning of the data in the BLOB columns is indicated
+ by the value in the MIME type column. This allows you to store different row types in
+ the same table. The Contacts Provider's "data" table
+ {@link android.provider.ContactsContract.Data} is an example of a schema-independent
+ table.
+ </p>
+ </li>
+</ul>
+<!-- Designing Content URIs -->
+<h2 id="ContentURI">Designing Content URIs</h2>
+<p>
+ A <strong>content URI</strong> is a URI that identifies data in a provider. Content URIs include
+ the symbolic name of the entire provider (its <strong>authority</strong>) and a
+ name that points to a table or file (a <strong>path</strong>). The optional id part points to
+ an individual row in a table. Every data access method of
+ {@link android.content.ContentProvider} has a content URI as an argument; this allows you to
+ determine the table, row, or file to access.
+</p>
+<p>
+ The basics of content URIs are described in the topic
+ <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
+ Content Provider Basics</a>.
+</p>
+<h3>Designing an authority</h3>
+<p>
+ A provider usually has a single authority, which serves as its Android-internal name. To
+ avoid conflicts with other providers, you should use Internet domain ownership (in reverse)
+ as the basis of your provider authority. Because this recommendation is also true for Android
+ package names, you can define your provider authority as an extension of the name
+ of the package containing the provider. For example, if your Android package name is
+ <code>com.example.<appname></code>, you should give your provider the
+ authority <code>com.example.<appname>.provider</code>.
+</p>
+<h3>Designing a path structure</h3>
+<p>
+ Developers usually create content URIs from the authority by appending paths that point to
+ individual tables. For example, if you have two tables <em>table1</em> and
+ <em>table2</em>, you combine the authority from the previous example to yield the
+ content URIs
+ <code>com.example.<appname>.provider/table1</code> and
+ <code>com.example.<appname>.provider/table2</code>. Paths aren't
+ limited to a single segment, and there doesn't have to be a table for each level of the path.
+</p>
+<h3>Handling content URI IDs</h3>
+<p>
+ By convention, providers offer access to a single row in a table by accepting a content URI
+ with an ID value for the row at the end of the URI. Also by convention, providers match the
+ ID value to the table's <code>_ID</code> column, and perform the requested access against the
+ row that matches.
+</p>
+<p>
+ This convention facilitates a common design pattern for apps accessing a provider. The app
+ does a query against the provider and displays the resulting {@link android.database.Cursor}
+ in a {@link android.widget.ListView} using a {@link android.widget.CursorAdapter}.
+ The definition of {@link android.widget.CursorAdapter} requires one of the columns in the
+ {@link android.database.Cursor} to be <code>_ID</code>
+</p>
+<p>
+ The user then picks one of the displayed rows from the UI in order to look at or modify the
+ data. The app gets the corresponding row from the {@link android.database.Cursor} backing the
+ {@link android.widget.ListView}, gets the <code>_ID</code> value for this row, appends it to
+ the content URI, and sends the access request to the provider. The provider can then do the
+ query or modification against the exact row the user picked.
+</p>
+<h3>Content URI patterns</h3>
+<p>
+ To help you choose which action to take for an incoming content URI, the provider API includes
+ the convenience class {@link android.content.UriMatcher}, which maps content URI "patterns" to
+ integer values. You can use the integer values in a <code>switch</code> statement that
+ chooses the desired action for the content URI or URIs that match a particular pattern.
+</p>
+<p>
+ A content URI pattern matches content URIs using wildcard characters:
+</p>
+ <ul>
+ <li>
+ <strong><code>*</code>:</strong> Matches a string of any valid characters of any length.
+ </li>
+ <li>
+ <strong><code>#</code>:</strong> Matches a string of numeric characters of any length.
+ </li>
+ </ul>
+<p>
+ As an example of designing and coding content URI handling, consider a provider with the
+ authority <code>com.example.app.provider</code> that recognizes the following content URIs
+ pointing to tables:
+</p>
+<ul>
+ <li>
+ <code>content://com.example.app.provider/table1</code>: A table called <code>table1</code>.
+ </li>
+ <li>
+ <code>content://com.example.app.provider/table2/dataset1</code>: A table called
+ <code>dataset1</code>.
+ </li>
+ <li>
+ <code>content://com.example.app.provider/table2/dataset2</code>: A table called
+ <code>dataset2</code>.
+ </li>
+ <li>
+ <code>content://com.example.app.provider/table3</code>: A table called <code>table3</code>.
+ </li>
+</ul>
+<p>
+ The provider also recognizes these content URIs if they have a row ID appended to them, as
+ for example <code>content://com.example.app.provider/table3/1</code> for the row identified by
+ <code>1</code> in <code>table3</code>.
+</p>
+<p>
+ The following content URI patterns would be possible:
+</p>
+<dl>
+ <dt>
+ <code>content://com.example.app.provider/*</code>
+ </dt>
+ <dd>
+ Matches any content URI in the provider.
+ </dd>
+ <dt>
+ <code>content://com.example.app.provider/table2/*</code>:
+ </dt>
+ <dd>
+ Matches a content URI for the tables <code>dataset1</code>
+ and <code>dataset2</code>, but doesn't match content URIs for <code>table1</code> or
+ <code>table3</code>.
+ </dd>
+ <dt>
+ <code>content://com.example.app.provider/table3/#</code>: Matches a content URI
+ for single rows in <code>table3</code>, such as
+ <code>content://com.example.app.provider/table3/6</code> for the row identified by
+ <code>6</code>.
+ </dt>
+</dl>
+<p>
+ The following code snippet shows how the methods in {@link android.content.UriMatcher} work.
+ This code handles URIs for an entire table differently from URIs for a
+ single row, by using the content URI pattern
+ <code>content://<authority>/<path></code> for tables, and
+ <code>content://<authority>/<path>/<id></code> for single rows.
+</p>
+<p>
+ The method {@link android.content.UriMatcher#addURI(String, String, int) addURI()} maps an
+ authority and path to an integer value. The method android.content.UriMatcher#match(Uri)
+ match()} returns the integer value for a URI. A <code>switch</code> statement
+ chooses between querying the entire table, and querying for a single record:
+</p>
+<pre class="prettyprint">
+public class ExampleProvider extends ContentProvider {
+...
+ // Creates a UriMatcher object.
+ private static final UriMatcher sUriMatcher;
+...
+ /*
+ * The calls to addURI() go here, for all of the content URI patterns that the provider
+ * should recognize. For this snippet, only the calls for table 3 are shown.
+ */
+...
+ /*
+ * Sets the integer value for multiple rows in table 3 to 1. Notice that no wildcard is used
+ * in the path
+ */
+ sUriMatcher.addURI("com.example.app.provider", "table3", 1);
+
+ /*
+ * Sets the code for a single row to 2. In this case, the "#" wildcard is
+ * used. "content://com.example.app.provider/table3/3" matches, but
+ * "content://com.example.app.provider/table3 doesn't.
+ */
+ sUriMatcher.addURI("com.example.app.provider", "table3/#", 2);
+...
+ // Implements ContentProvider.query()
+ public Cursor query(
+ Uri uri,
+ String[] projection,
+ String selection,
+ String[] selectionArgs,
+ String sortOrder) {
+...
+ /*
+ * Choose the table to query and a sort order based on the code returned for the incoming
+ * URI. Here, too, only the statements for table 3 are shown.
+ */
+ switch (sUriMatcher.match(uri)) {
+
+
+ // If the incoming URI was for all of table3
+ case 1:
+
+ if (TextUtils.isEmpty(sortOrder)) sortOrder = "_ID ASC";
+ break;
+
+ // If the incoming URI was for a single row
+ case 2:
+
+ /*
+ * Because this URI was for a single row, the _ID value part is
+ * present. Get the last path segment from the URI; this is the _ID value.
+ * Then, append the value to the WHERE clause for the query
+ */
+ selection = selection + "_ID = " uri.getLastPathSegment();
+ break;
+
+ default:
+ ...
+ // If the URI is not recognized, you should do some error handling here.
+ }
+ // call the code to actually do the query
+ }
+</pre>
+<p>
+ Another class, {@link android.content.ContentUris}, provides convenience methods for working
+ with the <code>id</code> part of content URIs. The classes {@link android.net.Uri} and
+ {@link android.net.Uri.Builder} include convenience methods for parsing existing
+ {@link android.net.Uri} objects and building new ones.
+</p>
+
+<!-- Implementing the ContentProvider class -->
+<h2 id="ContentProvider">Implementing the ContentProvider Class</h2>
+<p>
+ The {@link android.content.ContentProvider} instance manages access
+ to a structured set of data by handling requests from other applications. All forms
+ of access eventually call {@link android.content.ContentResolver}, which then calls a concrete
+ method of {@link android.content.ContentProvider} to get access.
+</p>
+<h3 id="RequiredAccess">Required methods</h3>
+<p>
+ The abstract class {@link android.content.ContentProvider} defines six abstract methods that
+ you must implement as part of your own concrete subclass. All of these methods except
+ {@link android.content.ContentProvider#onCreate() onCreate()} are called by a client application
+ that is attempting to access your content provider:
+</p>
+<dl>
+ <dt>
+ {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
+ query()}
+ </dt>
+ <dd>
+ Retrieve data from your provider. Use the arguments to select the table to
+ query, the rows and columns to return, and the sort order of the result.
+ Return the data as a {@link android.database.Cursor} object.
+ </dd>
+ <dt>
+ {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}
+ </dt>
+ <dd>
+ Insert a new row into your provider. Use the arguments to select the
+ destination table and to get the column values to use. Return a content URI for the
+ newly-inserted row.
+ </dd>
+ <dt>
+ {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[])
+ update()}
+ </dt>
+ <dd>
+ Update existing rows in your provider. Use the arguments to select the table and rows
+ to update and to get the updated column values. Return the number of rows updated.
+ </dd>
+ <dt>
+ {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()}
+ </dt>
+ <dd>
+ Delete rows from your provider. Use the arguments to select the table and the rows to
+ delete. Return the number of rows deleted.
+ </dd>
+ <dt>
+ {@link android.content.ContentProvider#getType(Uri) getType()}
+ </dt>
+ <dd>
+ Return the MIME type corresponding to a content URI. This method is described in more
+ detail in the section <a href="#MIMETypes">Implementing Content Provider MIME Types</a>.
+ </dd>
+ <dt>
+ {@link android.content.ContentProvider#onCreate() onCreate()}
+ </dt>
+ <dd>
+ Initialize your provider. The Android system calls this method immediately after it
+ creates your provider. Notice that your provider is not created until a
+ {@link android.content.ContentResolver} object tries to access it.
+ </dd>
+</dl>
+<p>
+ Notice that these methods have the same signature as the identically-named
+ {@link android.content.ContentResolver} methods.
+</p>
+<p>
+ Your implementation of these methods should account for the following:
+</p>
+<ul>
+ <li>
+ All of these methods except {@link android.content.ContentProvider#onCreate() onCreate()}
+ can be called by multiple threads at once, so they must be thread-safe. To learn
+ more about multiple threads, see the topic
+ <a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html">
+ Processes and Threads</a>.
+ </li>
+ <li>
+ Avoid doing lengthy operations in {@link android.content.ContentProvider#onCreate()
+ onCreate()}. Defer initialization tasks until they are actually needed.
+ The section <a href="#OnCreate">Implementing the onCreate() method</a>
+ discusses this in more detail.
+ </li>
+ <li>
+ Although you must implement these methods, your code does not have to do anything except
+ return the expected data type. For example, you may want to prevent other applications
+ from inserting data into some tables. To do this, you can ignore the call to
+ {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} and return
+ 0.
+ </li>
+</ul>
+<h3 id="Query">Implementing the query() method</h3>
+<p>
+ The
+ {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
+ ContentProvider.query()} method must return a {@link android.database.Cursor} object, or if it
+ fails, throw an {@link java.lang.Exception}. If you are using an SQLite database as your data
+ storage, you can simply return the {@link android.database.Cursor} returned by one of the
+ <code>query()</code> methods of the {@link android.database.sqlite.SQLiteDatabase} class.
+ If the query does not match any rows, you should return a {@link android.database.Cursor}
+ instance whose {@link android.database.Cursor#getCount()} method returns 0.
+ You should return <code>null</code> only if an internal error occurred during the query process.
+</p>
+<p>
+ If you aren't using an SQLite database as your data storage, use one of the concrete subclasses
+ of {@link android.database.Cursor}. For example, the {@link android.database.MatrixCursor} class
+ implements a cursor in which each row is an array of {@link java.lang.Object}. With this class,
+ use {@link android.database.MatrixCursor#addRow(Object[]) addRow()} to add a new row.
+</p>
+<p>
+ Remember that the Android system must be able to communicate the {@link java.lang.Exception}
+ across process boundaries. Android can do this for the following exceptions that may be useful
+ in handling query errors:
+</p>
+<ul>
+ <li>
+ {@link java.lang.IllegalArgumentException} (You may choose to throw this if your provider
+ receives an invalid content URI)
+ </li>
+ <li>
+ {@link java.lang.NullPointerException}
+ </li>
+</ul>
+<h3 id="Insert">Implementing the insert() method</h3>
+<p>
+ The {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()} method adds a
+ new row to the appropriate table, using the values in the {@link android.content.ContentValues}
+ argument. If a column name is not in the {@link android.content.ContentValues} argument, you
+ may want to provide a default value for it either in your provider code or in your database
+ schema.
+</p>
+<p>
+ This method should return the content URI for the new row. To construct this, append the new
+ row's <code>_ID</code> (or other primary key) value to the table's content URI, using
+ {@link android.content.ContentUris#withAppendedId(Uri, long) withAppendedId()}.
+</p>
+<h3 id="Delete">Implementing the delete() method</h3>
+<p>
+ The {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} method
+ does not have to physically delete rows from your data storage. If you are using a sync adapter
+ with your provider, you should consider marking a deleted row
+ with a "delete" flag rather than removing the row entirely. The sync adapter can
+ check for deleted rows and remove them from the server before deleting them from the provider.
+</p>
+<h3 id="Update">Implementing the update() method</h3>
+<p>
+ The {@link android.content.ContentProvider#update(Uri, ContentValues, String, String[])
+ update()} method takes the same {@link android.content.ContentValues} argument used by
+ {@link android.content.ContentProvider#insert(Uri, ContentValues) insert()}, and the
+ same <code>selection</code> and <code>selectionArgs</code> arguments used by
+ {@link android.content.ContentProvider#delete(Uri, String, String[]) delete()} and
+ {@link android.content.ContentProvider#query(Uri, String[], String, String[], String)
+ ContentProvider.query()}. This may allow you to re-use code between these methods.
+</p>
+<h3 id="OnCreate">Implementing the onCreate() method</h3>
+<p>
+ The Android system calls {@link android.content.ContentProvider#onCreate()
+ onCreate()} when it starts up the provider. You should perform only fast-running initialization
+ tasks in this method, and defer database creation and data loading until the provider actually
+ receives a request for the data. If you do lengthy tasks in
+ {@link android.content.ContentProvider#onCreate() onCreate()}, you will slow down your
+ provider's startup. In turn, this will slow down the response from the provider to other
+ applications.
+</p>
+<p>
+ For example, if you are using an SQLite database you can create
+ a new {@link android.database.sqlite.SQLiteOpenHelper} object in
+ {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()},
+ and then create the SQL tables the first time you open the database. To facilitate this, the
+ first time you call {@link android.database.sqlite.SQLiteOpenHelper#getWritableDatabase
+ getWritableDatabase()}, it automatically calls the
+ {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase)
+ SQLiteOpenHelper.onCreate()} method.
+</p>
+<p>
+ The following two snippets demonstrate the interaction between
+ {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()} and
+ {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase)
+ SQLiteOpenHelper.onCreate()}. The first snippet is the implementation of
+ {@link android.content.ContentProvider#onCreate() ContentProvider.onCreate()}:
+</p>
+<pre class="prettyprint">
+public class ExampleProvider extends ContentProvider
+
+ /*
+ * Defines a handle to the database helper object. The MainDatabaseHelper class is defined
+ * in a following snippet.
+ */
+ private MainDatabaseHelper mOpenHelper;
+
+ // Defines the database name
+ private static final String DBNAME = "mydb";
+
+ // Holds the database object
+ private SQLiteDatabase db;
+
+ public boolean onCreate() {
+
+ /*
+ * Creates a new helper object. This method always returns quickly.
+ * Notice that the database itself isn't created or opened
+ * until SQLiteOpenHelper.getWritableDatabase is called
+ */
+ mOpenHelper = new SQLiteOpenHelper(
+ getContext(), // the application context
+ DBNAME, // the name of the database)
+ null, // uses the default SQLite cursor
+ 1 // the version number
+ );
+
+ return true;
+ }
+
+ ...
+
+ // Implements the provider's insert method
+ public Cursor insert(Uri uri, ContentValues values) {
+ // Insert code here to determine which table to open, handle error-checking, and so forth
+
+ ...
+
+ /*
+ * Gets a writeable database. This will trigger its creation if it doesn't already exist.
+ *
+ */
+ db = mOpenHelper.getWritableDatabase();
+ }
+}
+</pre>
+<p>
+ The next snippet is the implementation of
+ {@link android.database.sqlite.SQLiteOpenHelper#onCreate(SQLiteDatabase)
+ SQLiteOpenHelper.onCreate()}, including a helper class:
+</p>
+<pre class="prettyprint">
+...
+// A string that defines the SQL statement for creating a table
+private static final String SQL_CREATE_MAIN = "CREATE TABLE " +
+ "main " + // Table's name
+ "(" + // The columns in the table
+ " _ID INTEGER PRIMARY KEY, " +
+ " WORD TEXT"
+ " FREQUENCY INTEGER " +
+ " LOCALE TEXT )";
+...
+/**
+ * Helper class that actually creates and manages the provider's underlying data repository.
+ */
+protected static final class MainDatabaseHelper extends SQLiteOpenHelper {
+
+ /*
+ * Instantiates an open helper for the provider's SQLite data repository
+ * Do not do database creation and upgrade here.
+ */
+ MainDatabaseHelper(Context context) {
+ super(context, DBNAME, null, 1);
+ }
+
+ /*
+ * Creates the data repository. This is called when the provider attempts to open the
+ * repository and SQLite reports that it doesn't exist.
+ */
+ public void onCreate(SQLiteDatabase db) {
+
+ // Creates the main table
+ db.execSQL(SQL_CREATE_MAIN);
+ }
+}
+</pre>
+
+
+<!-- Implementing ContentProvider MIME Types -->
+<h2 id="MIMETypes">Implementing ContentProvider MIME Types</h2>
+<p>
+ The {@link android.content.ContentProvider} class has two methods for returning MIME types:
+</p>
+<dl>
+ <dt>
+ {@link android.content.ContentProvider#getType(Uri) getType()}
+ </dt>
+ <dd>
+ One of the required methods that you must implement for any provider.
+ </dd>
+ <dt>
+ {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}
+ </dt>
+ <dd>
+ A method that you're expected to implement if your provider offers files.
+ </dd>
+</dl>
+<h3 id="TableMIMETypes">MIME types for tables</h3>
+<p>
+ The {@link android.content.ContentProvider#getType(Uri) getType()} method returns a
+ {@link java.lang.String} in MIME format that describes the type of data returned by the content
+ URI argument. The {@link android.net.Uri} argument can be a pattern rather than a specific URI;
+ in this case, you should return the type of data associated with content URIs that match the
+ pattern.
+</p>
+<p>
+ For common types of data such as as text, HTML, or JPEG,
+ {@link android.content.ContentProvider#getType(Uri) getType()} should return the standard
+ MIME type for that data. A full list of these standard types is available on the
+ <a href="http://www.iana.org/assignments/media-types/index.htm">IANA MIME Media Types</a>
+ website.
+</p>
+<p>
+ For content URIs that point to a row or rows of table data,
+ {@link android.content.ContentProvider#getType(Uri) getType()} should return
+ a MIME type in Android's vendor-specific MIME format:
+</p>
+<ul>
+ <li>
+ Type part: <code>vnd</code>
+ </li>
+ <li>
+ Subtype part:
+ <ul>
+ <li>
+ If the URI pattern is for a single row: <code>android.cursor.<strong>item</strong>/</code>
+ </li>
+ <li>
+ If the URI pattern is for more than one row: <code>android.cursor.<strong>dir</strong>/</code>
+ </li>
+ </ul>
+ </li>
+ <li>
+ Provider-specific part: <code>vnd.<name></code>.<code><type></code>
+ <p>
+ You supply the <code><name></code> and <code><type></code>.
+ The <code><name></code> value should be globally unique,
+ and the <code><type></code> value should be unique to the corresponding URI
+ pattern. A good choice for <code><name></code> is your company's name or
+ some part of your application's Android package name. A good choice for the
+ <code><type></code> is a string that identifies the table associated with the
+ URI.
+ </p>
+
+ </li>
+</ul>
+<p>
+ For example, if a provider's authority is
+ <code>com.example.app.provider</code>, and it exposes a table named
+ <code>table1</code>, the MIME type for multiple rows in <code>table1</code> is:
+</p>
+<pre>
+vnd.android.cursor.<strong>dir</strong>/vnd.com.example.provider.table1
+</pre>
+<p>
+ For a single row of <code>table1</code>, the MIME type is:
+</p>
+<pre>
+vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1
+</pre>
+<h3 id="FileMIMETypes">MIME types for files</h3>
+<p>
+ If your provider offers files, implement
+ {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}.
+ The method returns a {@link java.lang.String} array of MIME types for the files your provider
+ can return for a given content URI. You should filter the MIME types you offer by the MIME type
+ filter argument, so that you return only those MIME types that the client wants to handle.
+</p>
+<p>
+ For example, consider a provider that offers photo images as files in <code>.jpg</code>,
+ <code>.png</code>, and <code>.gif</code> format.
+ If an application calls {@link android.content.ContentResolver#getStreamTypes(Uri, String)
+ ContentResolver.getStreamTypes()} with the filter string <code>image/*</code> (something that
+ is an "image"),
+ then the {@link android.content.ContentProvider#getStreamTypes(Uri, String)
+ ContentProvider.getStreamTypes()} method should return the array:
+</p>
+<pre>
+{ "image/jpeg", "image/png", "image/gif"}
+</pre>
+<p>
+ If the app is only interested in <code>.jpg</code> files, then it can call
+ {@link android.content.ContentResolver#getStreamTypes(Uri, String)
+ ContentResolver.getStreamTypes()} with the filter string <code>*\/jpeg</code>, and
+ {@link android.content.ContentProvider#getStreamTypes(Uri, String)
+ ContentProvider.getStreamTypes()} should return:
+<pre>
+{"image/jpeg"}
+</pre>
+<p>
+ If your provider doesn't offer any of the MIME types requested in the filter string,
+ {@link android.content.ContentProvider#getStreamTypes(Uri, String) getStreamTypes()}
+ should return <code>null</code>.
+</p>
+
+
+<!-- Implementing a Contract Class -->
+<h2 id="ContractClass">Implementing a Contract Class</h2>
+<p>
+ A contract class is a <code>public final</code> class that contains constant definitions for the
+ URIs, column names, MIME types, and other meta-data that pertain to the provider. The class
+ establishes a contract between the provider and other applications by ensuring that the provider
+ can be correctly accessed even if there are changes to the actual values of URIs, column names,
+ and so forth.
+</p>
+<p>
+ A contract class also helps developers because it usually has mnemonic names for its constants,
+ so developers are less likely to use incorrect values for column names or URIs. Since it's a
+ class, it can contain Javadoc documentation. Integrated development environments such as
+ Eclipse can auto-complete constant names from the contract class and display Javadoc for the
+ constants.
+</p>
+<p>
+ Developers can't access the contract class's class file from your application, but they can
+ statically compile it into their application from a <code>.jar</code> file you provide.
+</p>
+<p>
+ The {@link android.provider.ContactsContract} class and its nested classes are examples of
+ contract classes.
+</p>
+<h2 id="Permissions">Implementing Content Provider Permissions</h2>
+<p>
+ Permissions and access for all aspects of the Android system are described in detail in the
+ topic <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>.
+ The topic <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a> also
+ described the security and permissions in effect for various types of storage.
+ In brief, the important points are:
+</p>
+<ul>
+ <li>
+ By default, data files stored on the device's internal storage are private to your
+ application and provider.
+ </li>
+ <li>
+ {@link android.database.sqlite.SQLiteDatabase} databases you create are private to your
+ application and provider.
+ </li>
+ <li>
+ By default, data files that you save to external storage are <em>public</em> and
+ <em>world-readable</em>. You can't use a content provider to restrict access to files in
+ external storage, because other applications can use other API calls to read and write them.
+ </li>
+ <li>
+ The method calls for opening or creating files or SQLite databases on your device's internal
+ storage can potentially give both read and write access to all other applications. If you
+ use an internal file or database as your provider's repository, and you give it
+ "world-readable" or "world-writeable" access, the permissions you set for your provider in
+ its manifest won't protect your data. The default access for files and databases in
+ internal storage is "private", and for your provider's repository you shouldn't change this.
+ </li>
+</ul>
+<p>
+ If you want to use content provider permissions to control access to your data, then you should
+ store your data in internal files, SQLite databases, or the "cloud" (for example,
+ on a remote server), and you should keep files and databases private to your application.
+</p>
+<h3>Implementing permissions</h3>
+<p>
+ All applications can read from or write to your provider, even if the underlying data is
+ private, because by default your provider does not have permissions set. To change this,
+ set permissions for your provider in your manifest file, using attributes or child
+ elements of the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element. You can set permissions that apply to the entire provider,
+ or to certain tables, or even to certain records, or all three.
+</p>
+<p>
+ You define permissions for your provider with one or more
+ <code><a href="{@docRoot}guide/topics/manifest/permission-element.html">
+ <permission></a></code> elements in your manifest file. To make the
+ permission unique to your provider, use Java-style scoping for the
+ <code><a href="{@docRoot}guide/topics/manifest/permission-element.html#nm">
+ android:name</a></code> attribute. For example, name the read permission
+ <code>com.example.app.provider.permission.READ_PROVIDER</code>.
+
+</p>
+<p>
+ The following list describes the scope of provider permissions, starting with the
+ permissions that apply to the entire provider and then becoming more fine-grained.
+ More fine-grained permissions take precedence over ones with larger scope:
+</p>
+<dl>
+ <dt>
+ Single read-write provider-level permission
+ </dt>
+ <dd>
+ One permission that controls both read and write access to the entire provider, specified
+ with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">
+ android:permission</a></code> attribute of the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element.
+ </dd>
+ <dt>
+ Separate read and write provider-level permission
+ </dt>
+ <dd>
+ A read permission and a write permission for the entire provider. You specify them
+ with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">
+ android:readPermission</a></code> and
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">
+ android:writePermission</a></code> attributes of the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element. They take precedence over the permission required by
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">
+ android:permission</a></code>.
+ </dd>
+ <dt>
+ Path-level permission
+ </dt>
+ <dd>
+ Read, write, or read/write permission for a content URI in your provider. You specify
+ each URI you want to control with a
+ <code><a href="{@docRoot}guide/topics/manifest/path-permission-element.html">
+ <path-permission></a></code> child element of the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element. For each content URI you specify, you can specify a
+ read/write permission, a read permission, or a write permission, or all three. The read and
+ write permissions take precedence over the read/write permission. Also, path-level
+ permission takes precedence over provider-level permissions.
+ </dd>
+ <dt>
+ Temporary permission
+ </dt>
+ <dd>
+ A permission level that grants temporary access to an application, even if the application
+ doesn't have the permissions that are normally required. The temporary
+ access feature reduces the number of permissions an application has to request in
+ its manifest. When you turn on temporary permissions, the only applications that need
+ "permanent" permissions for your provider are ones that continually access all
+ your data.
+ <p>
+ Consider the permissions you need to implement an email provider and app, when you
+ want to allow an outside image viewer application to display photo attachments from your
+ provider. To give the image viewer the necessary access without requiring permissions,
+ set up temporary permissions for content URIs for photos. Design your email app so
+ that when the user wants to display a photo, the app sends an intent containing the
+ photo's content URI and permission flags to the image viewer. The image viewer can
+ then query your email provider to retrieve the photo, even though the viewer doesn't
+ have the normal read permission for your provider.
+ </p>
+ <p>
+ To turn on temporary permissions, either set the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
+ android:grantUriPermissions</a></code> attribute of the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element, or add one or more
+ <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">
+ <grant-uri-permission></a></code> child elements to your
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element. If you use temporary permissions, you have to call
+ {@link android.content.Context#revokeUriPermission(Uri, int)
+ Context.revokeUriPermission()} whenever you remove support for a content URI from your
+ provider, and the content URI is associated with a temporary permission.
+ </p>
+ <p>
+ The attribute's value determines how much of your provider is made accessible.
+ If the attribute is set to <code>true</code>, then the system will grant temporary
+ permission to your entire provider, overriding any other permissions that are required
+ by your provider-level or path-level permissions.
+ </p>
+ <p>
+ If this flag is set to <code>false</code>, then you must add
+ <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html">
+ <grant-uri-permission></a></code> child elements to your
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element. Each child element specifies the content URI or
+ URIs for which temporary access is granted.
+ </p>
+ <p>
+ To delegate temporary access to an application, an intent must contain
+ the {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION} or the
+ {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION} flags, or both. These
+ are set with the {@link android.content.Intent#setFlags(int) setFlags()} method.
+ </p>
+ <p>
+ If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
+ android:grantUriPermissions</a></code> attribute is not present, it's assumed to be
+ <code>false</code>.
+ </p>
+ </dd>
+</dl>
+
+
+
+<!-- The Provider Element -->
+<h2 id="ProviderElement">The <provider> Element</h2>
+<p>
+ Like {@link android.app.Activity} and {@link android.app.Service} components,
+ a subclass of {@link android.content.ContentProvider}
+ must be defined in the manifest file for its application, using the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element. The Android system gets the following information from
+ the element:
+<dl>
+ <dt>
+ Authority
+ (<a href="{@docRoot}guide/topics/manifest/provider-element.html#auth">{@code
+ android:authorities}</a>)
+ </dt>
+ <dd>
+ Symbolic names that identify the entire provider within the system. This
+ attribute is described in more detail in the section
+ <a href="#ContentURI">Designing Content URIs</a>.
+ </dd>
+ <dt>
+ Provider class name
+ (<code>
+<a href="{@docRoot}guide/topics/manifest/provider-element.html#nm">android:name</a>
+ </code>)
+ </dt>
+ <dd>
+ The class that implements {@link android.content.ContentProvider}. This class is
+ described in more detail in the section
+ <a href="#ContentProvider">Implementing the ContentProvider Class</a>.
+ </dd>
+ <dt>
+ Permissions
+ </dt>
+ <dd>
+ Attributes that specify the permissions that other applications must have in order to access
+ the provider's data:
+ <ul>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">
+ android:grantUriPermssions</a></code>: Temporary permission flag.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">
+ android:permission</a></code>: Single provider-wide read/write permission.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">
+ android:readPermission</a></code>: Provider-wide read permission.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">
+ android:writePermission</a></code>: Provider-wide write permission.
+ </li>
+ </ul>
+ <p>
+ Permissions and their corresponding attributes are described in more
+ detail in the section
+ <a href="#Permissions">Implementing Content Provider Permissions</a>.
+ </p>
+ </dd>
+ <dt>
+ Startup and control attributes
+ </dt>
+ <dd>
+ These attributes determine how and when the Android system starts the provider, the
+ process characteristics of the provider, and other run-time settings:
+ <ul>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#enabled">
+ android:enabled</a></code>: Flag allowing the system to start the provider.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#exported">
+ android:exported</a></code>: Flag allowing other applications to use this provider.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#init">
+ android:initOrder</a></code>: The order in which this provider should be started,
+ relative to other providers in the same process.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#multi">
+ android:multiProcess</a></code>: Flag allowing the system to start the provider
+ in the same process as the calling client.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#proc">
+ android:process</a></code>: The name of the process in which the provider should
+ run.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#sync">
+ android:syncable</a></code>: Flag indicating that the provider's data is to be
+ sync'ed with data on a server.
+ </li>
+ </ul>
+ <p>
+ The attributes are fully documented in the dev guide topic for the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code>
+ element.
+ </p>
+ </dd>
+ <dt>
+ Informational attributes
+ </dt>
+ <dd>
+ An optional icon and label for the provider:
+ <ul>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#icon">
+ android:icon</a></code>: A drawable resource containing an icon for the provider.
+ The icon appears next to the provider's label in the list of apps in
+ <em>Settings</em> > <em>Apps</em> > <em>All</em>.
+ </li>
+ <li>
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#label">
+ android:label</a></code>: An informational label describing the provider or its
+ data, or both. The label appears in the list of apps in
+ <em>Settings</em> > <em>Apps</em> > <em>All</em>.
+ </li>
+ </ul>
+ <p>
+ The attributes are fully documented in the dev guide topic for the
+ <code><a href="{@docRoot}guide/topics/manifest/provider-element.html">
+ <provider></a></code> element.
+ </p>
+ </dd>
+</dl>
+
+<!-- Intent Access -->
+<h2 id="Intents">Intents and Data Access</h2>
+<p>
+ Applications can access a content provider indirectly with an {@link android.content.Intent}.
+ The application does not call any of the methods of {@link android.content.ContentResolver} or
+ {@link android.content.ContentProvider}. Instead, it sends an intent that starts an activity,
+ which is often part of the provider's own application. The destination activity is in charge of
+ retrieving and displaying the data in its UI. Depending on the action in the intent, the
+ destination activity may also prompt the user to make modifications to the provider's data.
+ An intent may also contain "extras" data that the destination activity displays
+ in the UI; the user then has the option of changing this data before using it to modify the
+ data in the provider.
+</p>
+<p>
+
+</p>
+<p>
+ You may want to use intent access to help ensure data integrity. Your provider may depend
+ on having data inserted, updated, and deleted according to strictly defined business logic. If
+ this is the case, allowing other applications to directly modify your data may lead to
+ invalid data. If you want developers to use intent access, be sure to document it thoroughly.
+ Explain to them why intent access using your own application's UI is better than trying to
+ modify the data with their code.
+</p>
+<p>
+ Handling an incoming intent that wishes to modify your provider's data is no different from
+ handling other intents. You can learn more about using intents by reading the topic
+ <a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>.
+</p>
diff --git a/docs/html/guide/topics/providers/content-providers.jd b/docs/html/guide/topics/providers/content-providers.jd
index 95331ce..1707f03 100644
--- a/docs/html/guide/topics/providers/content-providers.jd
+++ b/docs/html/guide/topics/providers/content-providers.jd
@@ -1,922 +1,96 @@
page.title=Content Providers
@jd:body
-
<div id="qv-wrapper">
<div id="qv">
-<h2>In this document</h2>
+
+<!-- In this document -->
+<h2>Topics</h2>
<ol>
-<li><a href="#basics">Content provider basics</a></li>
-<li><a href="#querying">Querying a content provider</a></li>
-<li><a href="#modifying">Modifying data in a provider</a></li>
-<li><a href="#creating">Creating a content provider</a></li>
-<li><a href="#urisum">Content URI summary</a></li>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
+ Content Provider Basics</a>
+ </li>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/content-provider-creating.html">
+ Creating a Content Provider</a>
+ </li>
+ <li>
+ <a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a>
+ </li>
</ol>
-<h2>Key classes</h2>
-<ol>
-<li>{@link android.content.ContentProvider}</li>
-<li>{@link android.content.ContentResolver}</li>
-<li>{@link android.database.Cursor}</li>
-</ol>
-
-<h2>See also</h2>
-<ol>
- <li><a href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar Provider</a></li>
-</ol>
+ <!-- Related Samples -->
+<h2>Related Samples</h2>
+ <ol>
+ <li>
+ <a href="{@docRoot}resources/samples/ContactManager/index.html">
+ Contact Manager</a> application
+ </li>
+ <li>
+ <a
+ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List2.html">
+ "Cursor (People)"
+ </a>
+ </li>
+ <li>
+ <a
+ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List7.html">
+ "Cursor (Phones)"</a>
+ </li>
+ </ol>
</div>
</div>
-
<p>
-Content providers store and retrieve data and make it accessible to all
-applications. They're the only way to share data across applications; there's
-no common storage area that all Android packages can access.
-</p>
-
-<p>
-Android ships with a number of content providers for common data types
-(audio, video, images, personal contact information, and so on). You can
-see some of them listed in the {@link android.provider android.provider}
-package. You can query these providers for the data they contain (although,
-for some, you must acquire the proper permission to read the data).
-</p>
-
-<p class="note"><strong>Note:</strong> Android 4.0 introduces the Calendar
-Provider. For more information, see <a
-href="{@docRoot}guide/topics/providers/calendar-provider.html">Calendar
-Provider</a>.</p>
-<p>
-If you want to make your own data public, you have two options: You can
-create your own content provider (a {@link android.content.ContentProvider}
-subclass) or you can add the data to an existing provider — if there's
-one that controls the same type of data and you have permission to write to it.
-</p>
-
-<p>
-This document is an introduction to using content providers. After a
-brief discussion of the fundamentals, it explores how to query a content
-provider, how to modify data controlled by a provider, and how to create
-a content provider of your own.
-</p>
-
-
-<h2><a name="basics"></a>Content Provider Basics</h2>
-
-<p>
-How a content provider actually stores its data under the covers is
-up to its designer. But all content providers implement a common interface
-for querying the provider and returning results — as well as for
-adding, altering, and deleting data.
-</p>
-
-<p>
-It's an interface that clients use indirectly, most generally through
-{@link android.content.ContentResolver} objects. You get a ContentResolver
-by calling <code>{@link android.content.Context#getContentResolver
-getContentResolver()}</code> from within the implementation of an Activity
-or other application component:
-</p>
-
-<pre>ContentResolver cr = getContentResolver();</pre>
-
-<p>
-You can then use the ContentResolver's methods to interact with whatever
-content providers you're interested in.
-</p>
-
-<p>
-When a query is initiated, the Android system identifies the content provider
-that's the target of the query and makes sure that it is up and running.
-The system instantiates all ContentProvider objects; you never need to do it
-on your own. In fact, you never deal directly with ContentProvider objects
-at all. Typically, there's just a single instance of each type of
-ContentProvider. But it can communicate with multiple ContentResolver objects
-in different applications and processes. The interaction between processes is
-handled by the ContentResolver and ContentProvider classes.
-</p>
-
-
-<h3>The data model</h3>
-
-<p>
-Content providers expose their data as a simple table on a database model,
-where each row is a record and each column is data of a particular type
-and meaning. For example, information about people and their phone numbers
-might be exposed as follows:
-</p>
-
-<table>
- <tr>
- <th scope="col">_ID</th>
- <th scope="col">NUMBER</th>
- <th scope="col">NUMBER_KEY</th>
- <th scope="col">LABEL</th>
- <th scope="col">NAME</th>
- <th scope="col">TYPE</th>
- </tr>
- <tr>
- <td>13</td>
- <td>(425) 555 6677</td>
- <td>425 555 6677</td>
- <td>Kirkland office</td>
- <td>Bully Pulpit</td>
- <td>{@code TYPE_WORK}</td>
- </tr>
- <tr>
- <td>44</td>
- <td>(212) 555-1234</td>
- <td>212 555 1234</td>
- <td>NY apartment</td>
- <td>Alan Vain</td>
- <td>{@code TYPE_HOME}</td>
- </tr>
- <tr>
- <td>45</td>
- <td>(212) 555-6657</td>
- <td>212 555 6657</td>
- <td>Downtown office</td>
- <td>Alan Vain</td>
- <td>{@code TYPE_MOBILE}</td>
- </tr>
- <tr>
- <td>53</td>
- <td>201.555.4433</td>
- <td>201 555 4433</td>
- <td>Love Nest</td>
- <td>Rex Cars</td>
- <td>{@code TYPE_HOME}</td>
- </tr>
-</table>
-
-<p>
-Every record includes a numeric {@code _ID} field that uniquely identifies
-the record within the table. IDs can be used to match records in related
-tables — for example, to find a person's phone number in one table
-and pictures of that person in another.
-</p>
-
-<p>
-A query returns a {@link android.database.Cursor} object that can move from
-record to record and column to column to read the contents of each field.
-It has specialized methods for reading each type of data. So, to read a field,
-you must know what type of data the field contains. (There's more on query
-results and Cursor objects later.)
-</p>
-
-
-<h3><a name="uri"></a>URIs</h3>
-
-<p>
-Each content provider exposes a public URI (wrapped as a {@link android.net.Uri}
-object) that uniquely identifies its data set. A content provider that controls
-multiple data sets (multiple tables) exposes a separate URI for each one. All
-URIs for providers begin with the string "{@code content://}". The {@code content:}
-scheme identifies the data as being controlled by a content provider.
-</p>
-
-<p>
-If you're defining a content provider, it's a good idea to also define a
-constant for its URI, to simplify client code and make future updates cleaner.
-Android defines {@code CONTENT_URI} constants for all the providers that come
-with the platform. For example, the URI for the table that matches
-phone numbers to people and the URI for the table that holds pictures of
-people (both controlled by the Contacts content provider) are:
-</p>
-
-<p>
-<p style="margin-left: 2em">{@code android.provider.Contacts.Phones.CONTENT_URI}
-<br/>{@code android.provider.Contacts.Photos.CONTENT_URI}
+ Content providers manage access to a structured set of data. They encapsulate the
+ data, and provide mechanisms for defining data security. Content providers are the standard
+ interface that connects data in one process with code running in another process.
</p>
-
<p>
-The URI constant is used in all interactions with the content provider.
-Every {@link android.content.ContentResolver} method takes the URI
-as its first argument. It's what identifies which provider the ContentResolver
-should talk to and which table of the provider is being targeted.
-</p>
-
-
-<h2><a name="querying"></a>Querying a Content Provider</h2>
-
-<p>
-You need three pieces of information to query a content provider:
-</p>
-
-<ul>
-<li>The URI that identifies the provider</li>
-<li>The names of the data fields you want to receive</li>
-<li>The data types for those fields</li>
-</ul>
-
-<p>
-If you're querying a particular record, you also need the ID for that record.
-</p>
-
-
-<h3>Making the query</h3>
-
-<p>
-To query a content provider, you can use either the
-<code>{@link android.content.ContentResolver#query ContentResolver.query()}</code>
-method or the <code>{@link android.app.Activity#managedQuery
-Activity.managedQuery()}</code> method.
-Both methods take the same set of arguments, and both return a
-Cursor object. However, {@code managedQuery()}
-causes the activity to manage the life cycle of the Cursor. A managed Cursor
-handles all of the niceties, such as unloading itself when the activity pauses,
-and requerying itself when the activity restarts. You can ask an Activity to
-begin managing an unmanaged Cursor object for you by calling
-<code>{@link android.app.Activity#startManagingCursor
-Activity.startManagingCursor()}</code>.
-</p>
-
-<p>
-The first argument to either <code>{@link android.content.ContentResolver#query query()}</code>
-or <code>{@link android.app.Activity#managedQuery managedQuery()}</code> is the provider URI
-— the {@code CONTENT_URI} constant that identifies a particular
-ContentProvider and data set (see <a href="#uri">URIs</a> earlier).
-</p>
-
-<p>
-To restrict a query to just one record, you can append the {@code _ID} value for
-that record to the URI — that is, place a string matching the ID as the
-last segment of the path part of the URI. For example, if the ID is 23,
-the URI would be:
-</p>
-
-<p style="margin-left: 2em">{@code content://. . . ./23}</p>
-
-<p>
-There are some helper methods, particularly
-<code>{@link android.content.ContentUris#withAppendedId
-ContentUris.withAppendedId()}</code> and <code>{@link
-android.net.Uri#withAppendedPath Uri.withAppendedPath()}</code>,
-that make it easy to append an ID to a URI. Both are static methods that return
-a Uri object with the ID added. So, for example, if you were looking for record
-23 in the database of people contacts, you might construct a query as follows:
-</p>
-
-<pre>
-import android.provider.Contacts.People;
-import android.content.ContentUris;
-import android.net.Uri;
-import android.database.Cursor;
-
-// Use the ContentUris method to produce the base URI for the contact with _ID == 23.
-Uri myPerson = ContentUris.withAppendedId(People.CONTENT_URI, 23);
-
-// Alternatively, use the Uri method to produce the base URI.
-// It takes a string rather than an integer.
-Uri myPerson = Uri.withAppendedPath(People.CONTENT_URI, "23");
-
-// Then query for this specific record:
-Cursor cur = managedQuery(myPerson, null, null, null, null);
-</pre>
-
-<p>
-The other arguments to the <code>{@link android.content.ContentResolver#query query()}</code>
-and <code>{@link android.app.Activity#managedQuery managedQuery()}</code> methods delimit
-the query in more detail. They are:
-</p>
-
-<ul>
-<li>The names of the data columns that should be returned. A {@code null}
-value returns all columns. Otherwise, only columns that are listed by name
-are returned. All the content providers that come with the platform define
-constants for their columns. For example, the
-{@link android.provider.Contacts.Phones android.provider.Contacts.Phones} class
-defines constants for the names of the columns in the phone table illustrated
-earlier — {@code _ID}, {@code NUMBER}, {@code NUMBER_KEY}, {@code NAME},
-and so on.</li>
-
-<li><p>A filter detailing which rows to return, formatted as an SQL {@code WHERE}
-clause (excluding the {@code WHERE} itself). A {@code null} value returns
-all rows (unless the URI limits the query to a single record).</p></li>
-
-<li><p>Selection arguments.</p></li>
-
-<li><p>A sorting order for the rows that are returned, formatted as an SQL
-{@code ORDER BY} clause (excluding the {@code ORDER BY} itself). A {@code null}
-value returns the records in the default order for the table, which may be
-unordered.</p></li>
-</ul>
-
-<p>
-Let's look at an example query to retrieve a list of contact names and their
-primary phone numbers:
+ When you want to access data in a content provider, you use the
+ {@link android.content.ContentResolver} object in your
+ application's {@link android.content.Context} to communicate with the provider as a client.
+ The {@link android.content.ContentResolver} object communicates with the provider object, an
+ instance of a class that implements {@link android.content.ContentProvider}. The provider
+ object receives data requests from clients, performs the requested action, and
+ returns the results.
</p>
-
-<pre>
-import android.provider.Contacts.People;
-import android.database.Cursor;
-
-// Form an array specifying which columns to return.
-String[] projection = new String[] {
- People._ID,
- People._COUNT,
- People.NAME,
- People.NUMBER
- };
-
-// Get the base URI for the People table in the Contacts content provider.
-Uri contacts = People.CONTENT_URI;
-
-// Make the query.
-Cursor managedCursor = managedQuery(contacts,
- projection, // Which columns to return
- null, // Which rows to return (all rows)
- null, // Selection arguments (none)
- // Put the results in ascending order by name
- People.NAME + " ASC");
-</pre>
-
<p>
-This query retrieves data from the People table of the Contacts content
-provider. It gets the name, primary phone number, and unique record ID for
-each contact. It also reports the number of records that are returned as
-the {@code _COUNT} field of each record.
+ You don't need to develop your own provider if you don't intend to share your data with
+ other applications. However, you do need your own provider to provide custom search
+ suggestions in your own application. You also need your own provider if you want to copy and
+ paste complex data or files from your application to other applications.
</p>
-
<p>
-The constants for the names of the columns are defined in various interfaces
-— {@code _ID} and {@code _COUNT} in
-{@link android.provider.BaseColumns BaseColumns}, {@code NAME} in {@link android.provider.Contacts.PeopleColumns PeopleColumns}, and {@code NUMBER}
-in {@link android.provider.Contacts.PhonesColumns PhoneColumns}. The
-{@link android.provider.Contacts.People Contacts.People} class implements
-each of these interfaces, which is why the code example above could refer
-to them using just the class name.
+ Android itself includes content providers that manage data such as audio, video, images, and
+ personal contact information. You can see some of them listed in the reference
+ documentation for the
+ <code><a href="{@docRoot}reference/android/provider/package-summary.html">android.provider</a>
+ </code> package. With some restrictions, these providers are accessible to any Android
+ application.
+</p><p>
+ The following topics describe content providers in more detail:
</p>
-
-
-<h3>What a query returns</h3>
-
-<p>
-A query returns a set of zero or more database records. The names of the
-columns, their default order, and their data types are specific to each
-content provider.
-But every provider has an {@code _ID} column, which holds a unique numeric
-ID for each record. Every provider can also report the number
-of records returned as the {@code _COUNT} column; its value
-is the same for all rows.
-</p>
-
-<p>
-Here is an example result set for the query in the previous section:
-</p>
-
-<table border="1">
- <tbody>
- <tr>
- <th scope="col">_ID</th>
- <th scope="col">_COUNT</th>
- <th scope="col">NAME</th>
- <th scope="col">NUMBER</th>
- </tr>
- <tr>
- <td>44</td>
- <td>3</td>
- <td>Alan Vain</td>
- <td>212 555 1234</td>
- </tr>
- <tr>
- <td>13</td>
- <td>3</td>
- <td>Bully Pulpit</td>
- <td>425 555 6677</td>
- </tr>
- <tr>
- <td>53</td>
- <td>3</td>
- <td>Rex Cars</td>
- <td>201 555 4433</td>
- </tr>
- </tbody>
-</table>
-
-<p>
-The retrieved data is exposed by a {@link android.database.Cursor Cursor}
-object that can be used to iterate backward or forward through the result
-set. You can use this object only to read the data. To add, modify, or
-delete data, you must use a ContentResolver object.
-</p>
-
-
-<h3>Reading retrieved data</h3>
-
-<p>
-The Cursor object returned by a query provides access to a recordset of
-results. If you have queried for a specific record by ID, this set will
-contain only one value. Otherwise, it can contain multiple values.
-(If there are no matches, it can also be empty.) You
-can read data from specific fields in the record, but you must know the
-data type of the field, because the Cursor object has a separate method
-for reading each type of data — such as <code>{@link
-android.database.Cursor#getString getString()}</code>, <code>{@link
-android.database.Cursor#getInt getInt()}</code>, and <code>{@link
-android.database.Cursor#getFloat getFloat()}</code>.
-(However, for most types, if you call the method for reading strings,
-the Cursor object will give you the String representation of the data.)
-The Cursor lets you request the column name from the index of the column,
-or the index number from the column name.
-</p>
-
-<p>
-The following snippet demonstrates reading names and phone numbers from
-the query illustrated earlier:
-</p>
-
-<pre>
-import android.provider.Contacts.People;
-
-private void getColumnData(Cursor cur){
- if (cur.moveToFirst()) {
-
- String name;
- String phoneNumber;
- int nameColumn = cur.getColumnIndex(People.NAME);
- int phoneColumn = cur.getColumnIndex(People.NUMBER);
- String imagePath;
-
- do {
- // Get the field values
- name = cur.getString(nameColumn);
- phoneNumber = cur.getString(phoneColumn);
-
- // Do something with the values.
- ...
-
- } while (cur.moveToNext());
-
- }
-}
-</pre>
-
-<p>
-If a query can return binary data, such as an image or sound, the data
-may be directly entered in the table or the table entry for that data may be
-a string specifying a {@code content:} URI that you can use to get the data.
-In general, smaller amounts of data (say, from 20 to 50K or less) are most often
-directly entered in the table and can be read by calling
-<code>{@link android.database.Cursor#getBlob Cursor.getBlob()}</code>.
-It returns a byte array.
-</p>
-
-<p>
-If the table entry is a {@code content:} URI, you should never try to open
-and read the file directly (for one thing, permissions problems can make this
-fail). Instead, you should call
-<code>{@link android.content.ContentResolver#openInputStream
-ContentResolver.openInputStream()}</code> to get an
-{@link java.io.InputStream} object that you can use to read the data.
-</p>
-
-
-<h2><a name="modifying"></a>Modifying Data</h2>
-
-<p>
-Data kept by a content provider can be modified by:
-</p>
-
-<ul>
-<p><li>Adding new records</li>
-<li>Adding new values to existing records</li>
-<li>Batch updating existing records</li>
-<li>Deleting records</li>
-</ul>
-
-<p>
-All data modification is accomplished using {@link android.content.ContentResolver}
-methods. Some content providers require a more restrictive permission for writing
-data than they do for reading it. If you don't have permission to write to a
-content provider, the ContentResolver methods will fail.
-</p>
-
-
-<h3>Adding records</h3>
-
-<p>
-To add a new record to a content provider, first set up a map of key-value pairs
-in a {@link android.content.ContentValues} object, where each key matches
-the name of a column in the content provider and the value is the desired
-value for the new record in that column. Then call <code>{@link
-android.content.ContentResolver#insert ContentResolver.insert()}</code> and pass
-it the URI of the provider and the ContentValues map. This method returns
-the full URI of the new record — that is, the provider's URI with
-the appended ID for the new record. You can then use this URI to query and
-get a Cursor over the new record, and to further modify the record.
-Here's an example:
-</p>
-
-<pre>
-import android.provider.Contacts.People;
-import android.content.ContentResolver;
-import android.content.ContentValues;
-
-ContentValues values = new ContentValues();
-
-// Add Abraham Lincoln to contacts and make him a favorite.
-values.put(People.NAME, "Abraham Lincoln");
-// 1 = the new contact is added to favorites
-// 0 = the new contact is not added to favorites
-values.put(People.STARRED, 1);
-
-Uri uri = getContentResolver().insert(People.CONTENT_URI, values);
-</pre>
-
-
-<h3>Adding new values</h3>
-
-<p>
-Once a record exists, you can add new information to it or modify
-existing information. For example, the next step in the example above would
-be to add contact information — like a phone number or an IM or e-mail
-address — to the new entry.
-</p>
-
-<p>
-The best way to add to a record in the Contacts database is to append
-the name of the table where the new data goes to the URI for the
-record, then use the amended URI to add the new data values. Each
-Contacts table exposes a name for this purpose as a {@code
-CONTENT_DIRECTORY} constant. The following code continues the previous
-example by adding a phone number and e-mail address for the record
-just created:
-</p>
-
-<pre>
-Uri phoneUri = null;
-Uri emailUri = null;
-
-// Add a phone number for Abraham Lincoln. Begin with the URI for
-// the new record just returned by insert(); it ends with the _ID
-// of the new record, so we don't have to add the ID ourselves.
-// Then append the designation for the phone table to this URI,
-// and use the resulting URI to insert the phone number.
-phoneUri = Uri.withAppendedPath(uri, People.Phones.CONTENT_DIRECTORY);
-
-values.clear();
-values.put(People.Phones.TYPE, People.Phones.TYPE_MOBILE);
-values.put(People.Phones.NUMBER, "1233214567");
-getContentResolver().insert(phoneUri, values);
-
-// Now add an email address in the same way.
-emailUri = Uri.withAppendedPath(uri, People.ContactMethods.CONTENT_DIRECTORY);
-
-values.clear();
-// ContactMethods.KIND is used to distinguish different kinds of
-// contact methods, such as email, IM, etc.
-values.put(People.ContactMethods.KIND, Contacts.KIND_EMAIL);
-values.put(People.ContactMethods.DATA, "test@example.com");
-values.put(People.ContactMethods.TYPE, People.ContactMethods.TYPE_HOME);
-getContentResolver().insert(emailUri, values);
-</pre>
-
-<p>
-You can place small amounts of binary data into a table by calling
-the version of <code>{@link android.content.ContentValues#put
-ContentValues.put()}</code> that takes a byte array.
-That would work for a small icon-like image or a short audio clip, for example.
-However, if you have a large amount of binary data to add, such as a photograph
-or a complete song, put a {@code content:} URI for the data in the table and call
-<code>{@link android.content.ContentResolver#openOutputStream
-ContentResolver.openOutputStream()}</code>
-with the file's URI. (That causes the content provider to store the data
-in a file and record the file path in a hidden field of the record.)
-</p>
-
-<p>
-In this regard, the {@link android.provider.MediaStore} content
-provider, the main provider that dispenses image, audio, and video
-data, employs a special convention: The same URI that is used with
-{@code query()} or {@code managedQuery()} to get meta-information
-about the binary data (such as, the caption of a photograph or the
-date it was taken) is used with {@code openInputStream()}
-to get the data itself. Similarly, the same URI that is used with
-{@code insert()} to put meta-information into a MediaStore record
-is used with {@code openOutputStream()} to place the binary data there.
-The following code snippet illustrates this convention:
-</p>
-
-<pre>
-import android.provider.MediaStore.Images.Media;
-import android.content.ContentValues;
-import java.io.OutputStream;
-
-// Save the name and description of an image in a ContentValues map.
-ContentValues values = new ContentValues(3);
-values.put(Media.DISPLAY_NAME, "road_trip_1");
-values.put(Media.DESCRIPTION, "Day 1, trip to Los Angeles");
-values.put(Media.MIME_TYPE, "image/jpeg");
-
-// Add a new record without the bitmap, but with the values just set.
-// insert() returns the URI of the new record.
-Uri uri = getContentResolver().insert(Media.EXTERNAL_CONTENT_URI, values);
-
-// Now get a handle to the file for that record, and save the data into it.
-// Here, sourceBitmap is a Bitmap object representing the file to save to the database.
-try {
- OutputStream outStream = getContentResolver().openOutputStream(uri);
- sourceBitmap.compress(Bitmap.CompressFormat.JPEG, 50, outStream);
- outStream.close();
-} catch (Exception e) {
- Log.e(TAG, "exception while writing image", e);
-}
-</pre>
-
-
-<h3>Batch updating records</h3>
-
-<p>
-To batch update a group of records (for example, to change "NY" to "New York"
-in all fields), call the <code>{@link
-android.content.ContentResolver#update ContentResolver.update()}</code>
-method with the columns and values to change.
-</p>
-
-
-<h3><a name="deletingrecord"></a>Deleting a record</h3>
-
-<p>
-To delete a single record, call {<code>{@link
-android.content.ContentResolver#delete ContentResolver.delete()}</code>
-with the URI of a specific row.
-</p>
-
-<p>
-To delete multiple rows, call <code>{@link
-android.content.ContentResolver#delete ContentResolver.delete()}</code>
-with the URI of the type of record to delete (for example, {@code android.provider.Contacts.People.CONTENT_URI}) and an SQL {@code WHERE}
-clause defining which rows to delete. (<i><b>Caution</b>:
-Be sure to include a valid {@code WHERE} clause if you're deleting a general
-type, or you risk deleting more records than you intended!</i>).
-</p>
-
-
-<h2><a name="creating"></a>Creating a Content Provider</h2>
-
-<p>
-To create a content provider, you must:
-</p>
-
-<ul>
-<li>Set up a system for storing the data. Most content providers
-store their data using Android's file storage methods or SQLite databases,
-but you can store your data any way you want. Android provides the
-{@link android.database.sqlite.SQLiteOpenHelper SQLiteOpenHelper}
-class to help you create a database and {@link
-android.database.sqlite.SQLiteDatabase SQLiteDatabase} to manage it.</li>
-
-<li><p>Extend the {@link android.content.ContentProvider} class to provide
-access to the data.</p></li>
-
-<li><p>Declare the content provider in the manifest file for your
-application (AndroidManifest.xml).</p></li>
-</ul>
-
-<p>
-The following sections have notes on the last two of these tasks.
-</p>
-
-
-<h3>Extending the ContentProvider class</h3>
-
-<p>
-You define a {@link android.content.ContentProvider} subclass to
-expose your data to others using the conventions expected by
-ContentResolver and Cursor objects. Principally, this means
-implementing six abstract methods declared in the ContentProvider class:
-</p>
-
-<p style="margin-left: 2em">{@code query()}
-<br/>{@code insert()}
-<br/>{@code update()}
-<br/>{@code delete()}
-<br/>{@code getType()}
-<br/>{@code onCreate()}</p>
-
-<p>
-The {@code query()} method must return a {@link android.database.Cursor} object
-that can iterate over the requested data. Cursor itself is an interface, but
-Android provides some ready-made Cursor objects that you can use. For example,
-{@link android.database.sqlite.SQLiteCursor} can iterate over data stored in
-an SQLite database. You get the Cursor object by calling any of the {@link
-android.database.sqlite.SQLiteDatabase SQLiteDatabase} class's {@code query()}
-methods. There are other Cursor implementations — such as {@link
-android.database.MatrixCursor} — for data not stored in a database.
-</p>
-
-<p>
-Because these ContentProvider methods can be called from
-various ContentResolver objects in different processes and threads,
-they must be implemented in a thread-safe manner.
-</p>
-
-<p>
-As a courtesy, you might also want to call <code>{@link android.content.ContentResolver#notifyChange(android.net.Uri,android.database.ContentObserver)
-ContentResolver.notifyChange()}</code> to notify listeners when there are
-modifications to the data.
-</p>
-
-<p>
-Beyond defining the subclass itself, there are other steps you should take
-to simplify the work of clients and make the class more accessible:
-</p>
-
-<ul>
-<li>Define a {@code public static final} {@link android.net.Uri}
-named {@code CONTENT_URI}. This is the string that represents the full
-{@code content:} URI that your content provider handles. You must define a
-unique string for this value. The best solution is to use the fully-qualified
-class name of the content provider (made lowercase). So, for example, the
-URI for a TransportationProvider class could be defined as follows:
-
-<pre>public static final Uri CONTENT_URI =
- Uri.parse("content://com.example.codelab.transportationprovider");</pre>
-
-<p>
-If the provider has subtables, also define {@code CONTENT_URI} constants for
-each of the subtables. These URIs should all have the same authority (since
-that identifies the content provider), and be distinguished only by their paths.
-For example:
-</p>
-
-<p style="margin-left: 2em">{@code content://com.example.codelab.transportationprovider/train}
-<br/>{@code content://com.example.codelab.transportationprovider/air/domestic}
-<br/>{@code content://com.example.codelab.transportationprovider/air/international}</p>
-
-<p>
-For an overview of {@code content:} URIs, see the <a href="#urisum">Content URI
-Summary</a> at the end of this document.
-</p></li>
-
-<li><p>Define the column names that the content provider will return to clients.
-If you are using an underlying database, these column names are typically
-identical to the SQL database column names they represent. Also define
-{@code public static} String constants that clients can use to specify
-the columns in queries and other instructions.
-</p>
-
-<p>
-Be sure to include an integer column named "{@code _id}"
-(with the constant {@code _ID}) for
-the IDs of the records. You should have this field whether or not you have
-another field (such as a URL) that is also unique among all records. If
-you're using the SQLite database, the {@code _ID} field should be the
-following type:
-</p>
-
-<p style="margin-left: 2em">{@code INTEGER PRIMARY KEY AUTOINCREMENT}</p>
-
-<p>
-The {@code AUTOINCREMENT} descriptor is optional. But without it, SQLite
-increments an ID counter field to the next number above the largest
-existing number in the column. If you delete the last row, the next row added
-will have the same ID as the deleted row. {@code AUTOINCREMENT} avoids this
-by having SQLite increment to the next largest value whether deleted or not.
-</p>
-</li>
-
-<li><p>Carefully document the data type of each column. Clients need this
-information to read the data.</p></li>
-
-<li><p>If you are handling a new data type, you must define a new MIME type
-to return in your implementation of <code>{@link
-android.content.ContentProvider#getType ContentProvider.getType()}</code>.
-The type depends in part on whether or not the {@code content:} URI submitted
-to {@code getType()} limits the request to a specific record. There's one
-form of the MIME type for a single record and another for multiple records.
-Use the {@link android.net.Uri Uri} methods to help determine what is being
-requested. Here is the general format for each type:</p></li>
-
-<ul>
-<li><p>For a single record: {@code vnd.android.cursor.item/vnd.<em>yourcompanyname.contenttype</em>}</p>
-
-<p>For example, a request for train record 122, like this URI,</p>
-<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains/122}</p>
-
-<p>might return this MIME type:</p>
-<p style="margin-left: 2em">{@code vnd.android.cursor.item/vnd.example.rail}</p>
-</li>
-
-<li><p>For multiple records: {@code vnd.android.cursor.dir/vnd.<em>yourcompanyname.contenttype</em>}</p>
-
-<p>For example, a request for all train records, like the following URI,</p>
-<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains}</p>
-
-<p>might return this MIME type:</p>
-<p style="margin-left: 2em">{@code vnd.android.cursor.dir/vnd.example.rail}</p>
-</li>
-</ul>
-
-<li><p>If you are exposing byte data that's too big to put in the table itself
-— such as a large bitmap file — the field that exposes the
-data to clients should actually contain a {@code content:} URI string.
-This is the field that gives clients access to the data file. The record
-should also have another field, named "{@code _data}" that lists the exact file
-path on the device for that file. This field is not intended to be read by
-the client, but by the ContentResolver. The client will call <code>{@link
-android.content.ContentResolver#openInputStream ContentResolver.openInputStream()}</code>
-on the user-facing field holding the URI for the item. The ContentResolver
-will request the "{@code _data}" field for that record, and because
-it has higher permissions than a client, it should be able to access
-that file directly and return a read wrapper for the file to the client.</p></li>
-
-</ul>
-
-<p>
-For an example of a private content provider implementation, see the
-NodePadProvider class in the Notepad sample application that ships with the SDK.
-</p>
-
-
-<h3>Declaring the content provider</h3>
-
-<p>
-To let the Android system know about the content provider you've developed,
-declare it with a {@code <provider>} element in the application's
-AndroidManifest.xml file. Content providers that are not declared in the
-manifest are not visible to the Android system
-</p>
-
-<p>
-The {@code name} attribute is the fully qualified name of the ContentProvider
-subclass. The {@code authorities} attribute is the authority part of the
-{@code content:} URI that identifies the provider.
-For example if the ContentProvider subclass is AutoInfoProvider, the
-{@code <provider>} element might look like this:
-</p>
-
-<pre>
-<provider android:name="com.example.autos.AutoInfoProvider"
- android:authorities="com.example.autos.autoinfoprovider"
- . . . />
-</provider>
-</pre>
-
-<p>
-Note that the {@code authorities} attribute omits the path part of a
-{@code content:} URI. For example, if AutoInfoProvider controlled subtables
-for different types of autos or different manufacturers,
-</p>
-
-<p style="margin-left: 2em">{@code content://com.example.autos.autoinfoprovider/honda}
-<br/>{@code content://com.example.autos.autoinfoprovider/gm/compact}
-<br/>{@code content://com.example.autos.autoinfoprovider/gm/suv}</p>
-
-<p>
-those paths would not be declared in the manifest. The authority is what
-identifies the provider, not the path; your provider can interpret the path
-part of the URI in any way you choose.
-</p>
-
-<p>
-Other {@code <provider>} attributes can set permissions to read and
-write data, provide for an icon and text that can be displayed to users,
-enable and disable the provider, and so on. Set the {@code multiprocess}
-attribute to "{@code true}" if data does not need to be synchronized between
-multiple running versions of the content provider. This permits an instance
-of the provider to be created in each client process, eliminating the need
-to perform IPC.
-</p>
-
-
-<h2><a name="urisum"></a>Content URI Summary</h2>
-
-<p>
-Here is a recap of the important parts of a content URI:
-</p>
-
-<p>
-<img src="{@docRoot}images/content_uri.png" alt="Elements of a content URI"
-height="80" width="528">
-</p>
-
-<ol type="A">
-<li>Standard prefix indicating that the data is controlled by a
-content provider. It's never modified.</li>
-
-<li><p>The authority part of the URI; it identifies the content provider.
-For third-party applications, this should be a fully-qualified class name
-(reduced to lowercase) to ensure uniqueness. The authority is declared in
-the {@code <provider>} element's {@code authorities} attribute:</p>
-
-<pre><provider android:name=".TransportationProvider"
- android:authorities="com.example.transportationprovider"
- . . . ></pre></li>
-
-<li><p>The path that the content provider uses to determine what kind of data is
-being requested. This can be zero or more segments long. If the content provider
-exposes only one type of data (only trains, for example), it can be absent.
-If the provider exposes several types, including subtypes, it can be several
-segments long — for example, "{@code land/bus}", "{@code land/train}",
-"{@code sea/ship}", and "{@code sea/submarine}" to give four possibilities.</p></li>
-
-<li><p>The ID of the specific record being requested, if any. This is the
-{@code _ID} value of the requested record. If the request is not limited to
-a single record, this segment and the trailing slash are omitted:</p>
-
-<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains}</p>
-</li>
-</ol>
-
-
+<dl>
+ <dt>
+ <strong><a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
+ Content Provider Basics</a></strong>
+ </dt>
+ <dd>
+ How to access data in a content provider when the data is organized in tables.
+ </dd>
+ <dt>
+ <strong><a href="{@docRoot}guide/topics/providers/content-provider-creating.html">
+ Creating a Content Provider</a></strong>
+ </dt>
+ <dd>
+ How to create your own content provider.
+ </dd>
+ <dt>
+ <strong><a href="{@docRoot}guide/topics/providers/calendar-provider.html">
+ Calendar Provider</a></strong>
+ </dt>
+ <dd>
+ How to access the Calendar Provider that is part of the Android platform.
+ </dd>
+</dl>
diff --git a/docs/html/index.jd b/docs/html/index.jd
index 9197b5d..c14c0ae 100644
--- a/docs/html/index.jd
+++ b/docs/html/index.jd
@@ -142,6 +142,20 @@
+ "href='{@docRoot}sdk/api_diff/15/changes.html'>diff report</a>. If you're new to Android, "
+ "get started with the <a href='/sdk/index.html'>SDK starter package</a>.</p>"
},
+
+ 'plus': {
+ 'layout':"imgLeft",
+ 'icon':"google-plus-small.png",
+ 'name':"Google+ Page",
+ 'img':"google-plus.png",
+ 'title':"Android Developers on Google+",
+ 'desc': "<p>We now have a Google+ page for <a "
++ "href='https://plus.google.com/108967384991768947849'>+Android Developers</a>. "
++ "We'll use it to host Hangouts for developers, talk about the latest releases, "
++ "development and design tips, and much more.</p>"
++ "<div style='margin-top:.7em'><g:plus href='https://plus.google.com/108967384991768947849' "
++ "size=\"smallbadge\" width=\"275\"></g:plus></div>"
+ },
'tv': {
'layout':"imgLeft",
@@ -186,5 +200,19 @@
</script>
<script type="text/javascript" src="{@docRoot}assets/carousel.js"></script>
<script type="text/javascript">
- initCarousel("sdk");
+ initCarousel("plus");
</script>
+
+<script type="text/javascript" src="https://plus.google.com/108967384991768947849"
+rel="publisher"></script>
+<script type="text/javascript">
+window.___gcfg = {lang: 'en'};
+(function()
+{var po = document.createElement("script");
+po.type = "text/javascript"; po.async = true;po.src = "https://apis.google.com/js/plusone.js";
+var s = document.getElementsByTagName("script")[0];
+s.parentNode.insertBefore(po, s);
+})();</script>
+<style type="text/css">
+ #___plus_0, #___plus_0 iframe, #___plus_0 { width: 275px !important; }
+</style>
diff --git a/docs/html/resources/community-more.jd b/docs/html/resources/community-more.jd
index df72926..3089d45 100644
--- a/docs/html/resources/community-more.jd
+++ b/docs/html/resources/community-more.jd
@@ -1,5 +1,5 @@
community=true
-page.title=IRC and Twitter
+page.title=IRC, G+, Twitter
@jd:body
<p>In addition to the <a href="community-groups.html">Android developer forums</a>, you can participate in the Android developer community through IRC and you can follow us on Twitter. </p>
@@ -45,8 +45,27 @@
</li>
</ul>
+
+<h3 id="gplus">Google+</h3>
+<p>We use a Google+ page to host Hangouts for developers, talk about the latest
+releases, development and design tips, and much more.</p>
+
+<div style='margin-top:1em'><g:plus href='https://plus.google.com/108967384991768947849'
+size='badge'></g:plus></div>
+
+
<h3 id="twitter">Twitter</h3>
<p>You can follow us on Twitter at this account:</p>
<p style="margin-left:2em;"><a href="http://twitter.com/androiddev">http://twitter.com/androiddev</a></p>
+<script type="text/javascript" src="https://plus.google.com/108967384991768947849"
+rel="publisher"></script>
+<script type="text/javascript">
+window.___gcfg = {lang: 'en'};
+(function()
+{var po = document.createElement("script");
+po.type = "text/javascript"; po.async = true;po.src = "https://apis.google.com/js/plusone.js";
+var s = document.getElementsByTagName("script")[0];
+s.parentNode.insertBefore(po, s);
+})();</script>
\ No newline at end of file
diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs
index 8df419f..628df9e 100644
--- a/docs/html/resources/resources_toc.cs
+++ b/docs/html/resources/resources_toc.cs
@@ -302,7 +302,7 @@
<span class="en">Developer Forums</span>
</a></li>
<li><a href="<?cs var:toroot ?>resources/community-more.html">
- <span class="en">IRC, Twitter</span>
+ <span class="en">IRC, G+, Twitter</span>
</a></li>
</ul>
</li>
diff --git a/docs/html/shareables/adl/2010Q2_Business_Overview.pdf b/docs/html/shareables/adl/2010Q2_Business_Overview.pdf
deleted file mode 100644
index c34ea15..0000000
--- a/docs/html/shareables/adl/2010Q2_Business_Overview.pdf
+++ /dev/null
Binary files differ
diff --git a/docs/html/shareables/adl/2010Q2_Market_Overview.pdf b/docs/html/shareables/adl/2010Q2_Market_Overview.pdf
deleted file mode 100644
index 3752258..0000000
--- a/docs/html/shareables/adl/2010Q2_Market_Overview.pdf
+++ /dev/null
Binary files differ
diff --git a/docs/html/shareables/adl/2010Q2_SDK_Overview.pdf b/docs/html/shareables/adl/2010Q2_SDK_Overview.pdf
deleted file mode 100644
index 8796584..0000000
--- a/docs/html/shareables/adl/2010Q2_SDK_Overview.pdf
+++ /dev/null
Binary files differ
diff --git a/docs/html/shareables/adl/2011Q3_Android_Market_for_Developers.pdf b/docs/html/shareables/adl/2011Q3_Android_Market_for_Developers.pdf
deleted file mode 100644
index 598a27e..0000000
--- a/docs/html/shareables/adl/2011Q3_Android_Market_for_Developers.pdf
+++ /dev/null
Binary files differ
diff --git a/docs/html/shareables/adl/2011Q3_Designing_UIs_for_Phones_and_Tablets.pdf b/docs/html/shareables/adl/2011Q3_Designing_UIs_for_Phones_and_Tablets.pdf
deleted file mode 100644
index 6ef41dd..0000000
--- a/docs/html/shareables/adl/2011Q3_Designing_UIs_for_Phones_and_Tablets.pdf
+++ /dev/null
Binary files differ
diff --git a/docs/html/shareables/adl/2011Q3_Introduction_to_Honeycomb_APIs.pdf b/docs/html/shareables/adl/2011Q3_Introduction_to_Honeycomb_APIs.pdf
deleted file mode 100755
index e56d2377..0000000
--- a/docs/html/shareables/adl/2011Q3_Introduction_to_Honeycomb_APIs.pdf
+++ /dev/null
Binary files differ
diff --git a/docs/html/shareables/icon_templates-v1.0.zip b/docs/html/shareables/icon_templates-v1.0.zip
deleted file mode 100644
index 94fbcdc..0000000
--- a/docs/html/shareables/icon_templates-v1.0.zip
+++ /dev/null
Binary files differ
diff --git a/docs/html/training/design-navigation/ancestral-temporal.jd b/docs/html/training/design-navigation/ancestral-temporal.jd
index 02e43e1..c0b1aef 100644
--- a/docs/html/training/design-navigation/ancestral-temporal.jd
+++ b/docs/html/training/design-navigation/ancestral-temporal.jd
@@ -21,6 +21,7 @@
<h2>You should also read</h2>
<ul>
+ <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: Navigation</a></li>
<li><a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a></li>
</ul>
@@ -30,6 +31,11 @@
<p>Now that users can navigate <a href="descendant-lateral.html">deep into</a> the application's screen hierarchy, we need to provide a method for navigating up the hierarchy, to parent and ancestor screens. Additionally, we should ensure that temporal navigation via the BACK button is respected to respect Android conventions.</p>
+<div class="design-announce">
+<p><strong>Back/Up Navigation Design</strong></p>
+ <p>For design guidelines, read Android Design's <a
+ href="{@docRoot}design/patterns/navigation.html">Navigation</a> pattern guide.</p>
+</div>
<h2 id="temporal-navigation">Support Temporal Navigation: <em>Back</em></h2>
@@ -49,7 +55,7 @@
<h2 id="ancestral-navigation">Provide Ancestral Navigation: <em>Up</em> and <em>Home</em></h2>
-<p>Before Android 3.0, the most common form of ancestral navigation was the <em>Home</em> metaphor. This was generally implemented as a <em>Home</em> item accessible via the device's MENU button, or a <em>Home</em> button at the top-left of the screen, usually as a component of the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>. Upon selecting <em>Home</em>, the user would be taken to the screen at the top of the screen hierarchy, generally known as the application's home screen.</p>
+<p>Before Android 3.0, the most common form of ancestral navigation was the <em>Home</em> metaphor. This was generally implemented as a <em>Home</em> item accessible via the device's MENU button, or a <em>Home</em> button at the top-left of the screen, usually as a component of the Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design). Upon selecting <em>Home</em>, the user would be taken to the screen at the top of the screen hierarchy, generally known as the application's home screen.</p>
<p>Providing direct access to the application's home screen can give the user a sense of comfort and security. Regardless of where they are in the application, if they get lost in the app, they can select <em>Home</em> to arrive back at the familiar home screen.</p>
diff --git a/docs/html/training/design-navigation/descendant-lateral.jd b/docs/html/training/design-navigation/descendant-lateral.jd
index ebfd913..0064bd4 100644
--- a/docs/html/training/design-navigation/descendant-lateral.jd
+++ b/docs/html/training/design-navigation/descendant-lateral.jd
@@ -18,9 +18,18 @@
<li><a href="#buttons">Buttons and Simple Targets</a></li>
<li><a href="#lists">Lists, Grids, Carousels, and Stacks</a></li>
<li><a href="#tabs">Tabs</a></li>
- <li><a href="#paging">Horizontal Paging</a></li>
+ <li><a href="#paging">Horizontal Paging (Swipe Views)</a></li>
</ol>
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}design/building-blocks/buttons.html">Android Design: Buttons</a></li>
+ <li><a href="{@docRoot}design/building-blocks/lists.html">Android Design: Lists</a></li>
+ <li><a href="{@docRoot}design/building-blocks/grid-lists.html">Android Design: Grid Lists</a></li>
+ <li><a href="{@docRoot}design/building-blocks/tabs.html">Android Design: Tabs</a></li>
+ <li><a href="{@docRoot}design/patterns/swipe-views.html">Android Design: Swipe Views</a></li>
+</ul>
+
</div>
</div>
@@ -48,6 +57,12 @@
<h2 id="buttons">Buttons and Simple Targets</h2>
+<div class="design-announce">
+<p><strong>Button Design</strong></p>
+ <p>For design guidelines, read Android Design's <a
+ href="{@docRoot}design/building-blocks/buttons.html">Buttons</a> guide.</p>
+</div>
+
<p>For section-related screens, offering touchable and keyboard-focusable targets in the parent is generally the most straightforward and familiar kind of touch-based navigation interface. Examples of such targets include buttons, fixed-size list views, or text links, although the latter is not an ideal UI (user interface) element for touch-based navigation. Upon selecting one of these targets, the child screen is opened, replacing the current context (screen) entirely. Buttons and other simple targets are rarely used for representing items in a collection.</p>
@@ -64,6 +79,13 @@
<h2 id="lists">Lists, Grids, Carousels, and Stacks</h2>
+<div class="design-announce">
+<p><strong>List and Grid List Design</strong></p>
+ <p>For design guidelines, read Android Design's <a
+ href="{@docRoot}design/building-blocks/lists.html">Lists</a> and <a
+ href="{@docRoot}design/building-blocks/grid-lists.html">Grid Lists</a> guides.</p>
+</div>
+
<p>For collection-related screens, and especially for textual information, vertically scrolling lists are often the most straightforward and familiar kind of interface. For more visual or media-rich content items such as photos or videos, vertically scrolling grids of items, horizontally scrolling lists (sometimes referred to as <em>carousels</em>), or stacks (sometimes referred to as <em>cards</em>) can be used instead. These UI elements are generally best used for presenting item collections or large sets of child screens (for example, a list of stories or a list of 10 or more news topics), rather than a small set of unrelated, sibling child screens.</p>
@@ -80,6 +102,12 @@
<h2 id="tabs">Tabs</h2>
+<div class="design-announce">
+<p><strong>Tab Design</strong></p>
+ <p>For design guidelines, read Android Design's <a
+ href="{@docRoot}design/building-blocks/tabs.html">Tabs</a> guide.</p>
+</div>
+
<p>Using tabs is a very popular solution for lateral navigation. This pattern allows grouping of sibling screens, in that the tab content container in the parent screen can embed child screens that otherwise would be entirely separate contexts. Tabs are most appropriate for small sets (4 or fewer) of section-related screens.</p>
@@ -89,7 +117,7 @@
<p class="img-caption"><strong>Figure 5.</strong> Example phone and tablet tab-based navigation interfaces with relevant screen map excerpt.</p>
-<p>Several best practices apply when using tabs. Tabs should be persistent across immediate related screens. Only the designated content region should change when selecting a tab, and tab indicators should remain available at all times. Additionally, tab switches should not be treated as history. For example, if a user switches from a tab <em>A</em> to another tab <em>B</em>, pressing the BACK button (more on that in the <a href="ancestral-temporal.html">next lesson</a>) should not re-select tab <em>A</em>. Tabs are usually laid out horizontally, although other presentations of tab navigation such as using a drop-down list in the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> are sometimes appropriate. Lastly, and most importantly, <em>tabs should always run along the top of the screen</em>, and should not be aligned to the bottom of the screen.</p>
+<p>Several best practices apply when using tabs. Tabs should be persistent across immediate related screens. Only the designated content region should change when selecting a tab, and tab indicators should remain available at all times. Additionally, tab switches should not be treated as history. For example, if a user switches from a tab <em>A</em> to another tab <em>B</em>, pressing the BACK button (more on that in the <a href="ancestral-temporal.html">next lesson</a>) should not re-select tab <em>A</em>. Tabs are usually laid out horizontally, although other presentations of tab navigation such as using a drop-down list in the Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design) are sometimes appropriate. Lastly, and most importantly, <em>tabs should always run along the top of the screen</em>, and should not be aligned to the bottom of the screen.</p>
<p>There are some obvious immediate benefits of tabs over simpler list- and button-based navigation:</p>
@@ -101,9 +129,15 @@
<p>A common criticism is that space must be reserved for the tab indicators, detracting from the space available to tab contents. This consequence is usually acceptable, and the tradeoff commonly weighs in favor of using this pattern. You should also feel free to customize tab indicators, showing text and/or icons to make optimal use of vertical space. When adjusting indicator heights however, ensure that tab indicators are large enough for a human finger to touch without error.</p>
-<h2 id="paging">Horizontal Paging</h2>
+<h2 id="paging">Horizontal Paging (Swipe Views)</h2>
-<p>Another popular lateral navigation pattern is horizontal paging. This pattern applies best to collection-related sibling screens, such as a list of categories (world, business, technology, and health stories). Like tabs, this pattern also allows grouping screens in that the parent presents the contents of child screens embedded within its own layout.</p>
+<div class="design-announce">
+<p><strong>Swipe Views Design</strong></p>
+ <p>For design guidelines, read Android Design's <a
+ href="{@docRoot}design/patterns/swipe-views.html">Swipe Views</a> pattern guides.</p>
+</div>
+
+<p>Another popular lateral navigation pattern is horizontal paging, also referred to as swipe views. This pattern applies best to collection-related sibling screens, such as a list of categories (world, business, technology, and health stories). Like tabs, this pattern also allows grouping screens in that the parent presents the contents of child screens embedded within its own layout.</p>
<img src="{@docRoot}images/training/app-navigation-descendant-lateral-paging.png"
diff --git a/docs/html/training/design-navigation/index.jd b/docs/html/training/design-navigation/index.jd
index e02d52e..cb20a60 100644
--- a/docs/html/training/design-navigation/index.jd
+++ b/docs/html/training/design-navigation/index.jd
@@ -14,7 +14,7 @@
<p>This class is not specific to any particular version of the Android platform. It is also primarily design-focused and does not require knowledge of the Android SDK. That said, you should have experience using an Android device for a better understanding of the context in which Android applications run.</p>
-<p>You should also have basic familiarity with the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, used across most applications in devices running Android 3.0 and later.</p>
+<p>You should also have basic familiarity with the Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design), used across most applications in devices running Android 3.0 and later.</p>
</div>
diff --git a/docs/html/training/design-navigation/multiple-sizes.jd b/docs/html/training/design-navigation/multiple-sizes.jd
index 7a8139f..ebaec0f 100644
--- a/docs/html/training/design-navigation/multiple-sizes.jd
+++ b/docs/html/training/design-navigation/multiple-sizes.jd
@@ -22,6 +22,7 @@
<h2>You should also read</h2>
<ul>
+ <li><a href="{@docRoot}design/patterns/multi-pane-layouts.html">Android Design: Multi-pane Layouts</a></li>
<li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a></li>
</ul>
@@ -35,6 +36,12 @@
<h2 id="multi-pane-layouts">Group Screens with Multi-pane Layouts</h2>
+<div class="design-announce">
+<p><strong>Multi-pane Layout Design</strong></p>
+ <p>For design guidelines, read Android Design's <a
+ href="{@docRoot}design/patterns/multi-pane-layouts.html">Multi-pane Layouts</a> pattern guide.</p>
+</div>
+
<p>3 to 4-inch screens are generally only suitable for showing a single vertical pane of content at a time, be it a list of items, or detail information about an item, etc. Thus on such devices, screens generally map one-to-one with levels in the information hierarchy (<em>categories</em> → <em>object list</em> → <em>object detail</em>).</p>
<p>Larger screens such as those found on tablets and TVs, on the other hand, generally have much more available screen space and are able to present multiple panes of content. In landscape, panes are usually ordered from left to right in increasing detail order. Users are especially accustomed to multiple panes on larger screens from years and years of desktop application and desktop web site use. Many desktop applications and websites offer a left-hand navigation pane or use a master/detail two-pane layout.</p>
@@ -76,12 +83,12 @@
<li><strong>Expand/collapse</strong>
<img src="{@docRoot}images/training/app-navigation-multiple-sizes-strategy-collapse.png"
alt="Expand/collapse strategy">
- <p>A variation on the stretch strategy is to collapse the contents of the left pane when in portrait. This works quite well with master/detail panes where the left (master) pane contains easily collapsible list items. An example would be for a realtime chat application. In landscape, the left list could contain chat contact photos, names, and online statuses. In portrait, horizontal space could be collapsed by hiding contact names and only showing photos and online status indicator icons.</p></li>
+ <p>A variation on the stretch strategy is to collapse the contents of the left pane when in portrait. This works quite well with master/detail panes where the left (master) pane contains easily collapsible list items. An example would be for a realtime chat application. In landscape, the left list could contain chat contact photos, names, and online statuses. In portrait, horizontal space could be collapsed by hiding contact names and only showing photos and online status indicator icons. Optionally also provide an expand control that allows the user to expand the left pane content to its larger width and vice versa.</p></li>
<li><strong>Show/Hide</strong>
<img src="{@docRoot}images/training/app-navigation-multiple-sizes-strategy-show-hide.png"
alt="Show/Hide strategy">
- <p>In this scenario, the left pane is completely hidden in portrait mode. However, <em>to ensure the functional parity</em> of your screen in portrait and landscape, the left pane should be made available via an onscreen affordance (such as a button). It's usually appropriate to use the <em>Up</em> button in the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> to show the left pane, as is discussed in a <a href="ancestral-temporal.html">later lesson</a>.</p></li>
+ <p>In this scenario, the left pane is completely hidden in portrait mode. However, <em>to ensure the functional parity</em> of your screen in portrait and landscape, the left pane should be made available via an onscreen affordance (such as a button). It's usually appropriate to use the <em>Up</em> button in the Action Bar (<a href="{@docRoot}design/patterns/actionbar.html">pattern docs</a> at Android Design) to show the left pane, as is discussed in a <a href="ancestral-temporal.html">later lesson</a>.</p></li>
<li><strong>Stack</strong>
<img src="{@docRoot}images/training/app-navigation-multiple-sizes-strategy-stack.png"
diff --git a/docs/html/training/design-navigation/wireframing.jd b/docs/html/training/design-navigation/wireframing.jd
index c7687dd..6deceb1 100644
--- a/docs/html/training/design-navigation/wireframing.jd
+++ b/docs/html/training/design-navigation/wireframing.jd
@@ -121,5 +121,5 @@
<li><a href="{@docRoot}guide/topics/ui/index.html">Developer's Guide: User Interface</a>: learn how to implement your user interface designs using the Android SDK.</li>
<li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>: implement tabs, up navigation, on-screen actions, etc.
<li><a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a>: implement re-usable, multi-pane layouts
- <li><a href="{@docRoot}sdk/compatibility-library.html">Support Library</a>: implement horizontal paging using <code>ViewPager</code></li>
+ <li><a href="{@docRoot}sdk/compatibility-library.html">Support Library</a>: implement horizontal paging (swipe views) using <code>ViewPager</code></li>
</ul>
diff --git a/packages/SystemUI/res/layout-sw600dp/status_bar_notification_panel_title.xml b/packages/SystemUI/res/layout-sw600dp/status_bar_notification_panel_title.xml
index ef95936..b985aaf 100644
--- a/packages/SystemUI/res/layout-sw600dp/status_bar_notification_panel_title.xml
+++ b/packages/SystemUI/res/layout-sw600dp/status_bar_notification_panel_title.xml
@@ -63,6 +63,7 @@
android:layout_height="wrap_content"
android:layout_width="wrap_content"
android:layout_gravity="center_vertical"
+ android:paddingRight="6dp"
>
<ImageView
@@ -87,7 +88,6 @@
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:paddingRight="12dp"
- android:paddingLeft="6dp"
android:singleLine="true"
android:ellipsize="end"
android:text="@string/status_bar_settings_settings_button"
@@ -99,6 +99,7 @@
android:layout_height="wrap_content"
android:layout_width="wrap_content"
android:layout_gravity="center_vertical"
+ android:paddingRight="6dp"
>
<ImageView
@@ -122,7 +123,6 @@
android:layout_gravity="left|center_vertical"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
- android:paddingLeft="6dp"
android:paddingRight="12dp"
android:singleLine="true"
android:ellipsize="end"
diff --git a/packages/SystemUI/src/com/android/systemui/statusbar/policy/NetworkController.java b/packages/SystemUI/src/com/android/systemui/statusbar/policy/NetworkController.java
index d09e680..d46ab6c 100644
--- a/packages/SystemUI/src/com/android/systemui/statusbar/policy/NetworkController.java
+++ b/packages/SystemUI/src/com/android/systemui/statusbar/policy/NetworkController.java
@@ -890,34 +890,51 @@
if (!mHasMobileDataFeature) {
mDataSignalIconId = mPhoneSignalIconId = 0;
- } else if (mDataConnected) {
- mobileLabel = mNetworkName;
- if (DEBUG) {
- mobileLabel += "yyyyYYYYyyyyYYYY";
- }
- combinedSignalIconId = mDataSignalIconId;
- switch (mDataActivity) {
- case TelephonyManager.DATA_ACTIVITY_IN:
- mMobileActivityIconId = R.drawable.stat_sys_signal_in;
- break;
- case TelephonyManager.DATA_ACTIVITY_OUT:
- mMobileActivityIconId = R.drawable.stat_sys_signal_out;
- break;
- case TelephonyManager.DATA_ACTIVITY_INOUT:
- mMobileActivityIconId = R.drawable.stat_sys_signal_inout;
- break;
- default:
- mMobileActivityIconId = 0;
- break;
+ mobileLabel = "";
+ } else {
+ // We want to show the carrier name if in service and either:
+ // - We are connected to mobile data, or
+ // - We are not connected to mobile data, as long as the *reason* packets are not
+ // being routed over that link is that we have better connectivity via wifi.
+ // If data is disconnected for some other reason but wifi is connected, we show nothing.
+ // Otherwise (nothing connected) we show "No internet connection".
+
+ if (mDataConnected) {
+ mobileLabel = mNetworkName;
+ } else if (mWifiConnected) {
+ if (hasService()) {
+ mobileLabel = mNetworkName;
+ } else {
+ mobileLabel = "";
+ }
+ } else {
+ mobileLabel
+ = context.getString(R.string.status_bar_settings_signal_meter_disconnected);
}
- combinedLabel = mobileLabel;
- combinedActivityIconId = mMobileActivityIconId;
- combinedSignalIconId = mDataSignalIconId; // set by updateDataIcon()
- mContentDescriptionCombinedSignal = mContentDescriptionDataType;
- } else {
- mobileLabel = mHasMobileDataFeature ?
- context.getString(R.string.status_bar_settings_signal_meter_disconnected) : "";
+ // Now for things that should only be shown when actually using mobile data.
+ if (mDataConnected) {
+ combinedSignalIconId = mDataSignalIconId;
+ switch (mDataActivity) {
+ case TelephonyManager.DATA_ACTIVITY_IN:
+ mMobileActivityIconId = R.drawable.stat_sys_signal_in;
+ break;
+ case TelephonyManager.DATA_ACTIVITY_OUT:
+ mMobileActivityIconId = R.drawable.stat_sys_signal_out;
+ break;
+ case TelephonyManager.DATA_ACTIVITY_INOUT:
+ mMobileActivityIconId = R.drawable.stat_sys_signal_inout;
+ break;
+ default:
+ mMobileActivityIconId = 0;
+ break;
+ }
+
+ combinedLabel = mobileLabel;
+ combinedActivityIconId = mMobileActivityIconId;
+ combinedSignalIconId = mDataSignalIconId; // set by updateDataIcon()
+ mContentDescriptionCombinedSignal = mContentDescriptionDataType;
+ }
}
if (mWifiConnected) {
@@ -949,6 +966,12 @@
combinedLabel = wifiLabel;
combinedSignalIconId = mWifiIconId; // set by updateWifiIcons()
mContentDescriptionCombinedSignal = mContentDescriptionWifi;
+ } else {
+ if (mHasMobileDataFeature) {
+ wifiLabel = "";
+ } else {
+ wifiLabel = context.getString(R.string.status_bar_settings_signal_meter_disconnected);
+ }
}
if (mBluetoothTethered) {
@@ -969,9 +992,17 @@
mDataTypeIconId = 0;
// combined values from connected wifi take precedence over airplane mode
- if (!mWifiConnected) {
- wifiLabel = context.getString(R.string.status_bar_settings_signal_meter_disconnected);
- combinedLabel = wifiLabel;
+ if (mWifiConnected) {
+ // Suppress "No internet connection." from mobile if wifi connected.
+ mobileLabel = "";
+ } else {
+ if (mHasMobileDataFeature) {
+ // let the mobile icon show "No internet connection."
+ wifiLabel = "";
+ } else {
+ wifiLabel = context.getString(R.string.status_bar_settings_signal_meter_disconnected);
+ combinedLabel = wifiLabel;
+ }
mContentDescriptionCombinedSignal = mContentDescriptionPhoneSignal;
combinedSignalIconId = mDataSignalIconId;
}
diff --git a/services/java/com/android/server/connectivity/Tethering.java b/services/java/com/android/server/connectivity/Tethering.java
index ed7324c..cc1df4f 100644
--- a/services/java/com/android/server/connectivity/Tethering.java
+++ b/services/java/com/android/server/connectivity/Tethering.java
@@ -55,6 +55,7 @@
import java.io.FileDescriptor;
import java.io.PrintWriter;
import java.net.InetAddress;
+import java.net.Inet4Address;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
@@ -1326,7 +1327,17 @@
String[] dnsServers = mDefaultDnsServers;
Collection<InetAddress> dnses = linkProperties.getDnses();
if (dnses != null) {
- dnsServers = NetworkUtils.makeStrings(dnses);
+ // we currently only handle IPv4
+ ArrayList<InetAddress> v4Dnses =
+ new ArrayList<InetAddress>(dnses.size());
+ for (InetAddress dnsAddress : dnses) {
+ if (dnsAddress instanceof Inet4Address) {
+ v4Dnses.add(dnsAddress);
+ }
+ }
+ if (v4Dnses.size() > 0) {
+ dnsServers = NetworkUtils.makeStrings(v4Dnses);
+ }
}
try {
mNMService.setDnsForwarders(dnsServers);
@@ -1384,11 +1395,12 @@
boolean mTryCell = !WAIT_FOR_NETWORK_TO_SETTLE;
@Override
public void enter() {
+ turnOnMasterTetherSettings(); // may transition us out
+
mTryCell = !WAIT_FOR_NETWORK_TO_SETTLE; // better try something first pass
// or crazy tests cases will fail
chooseUpstreamType(mTryCell);
mTryCell = !mTryCell;
- turnOnMasterTetherSettings(); // may transition us out
}
@Override
public void exit() {
diff --git a/telephony/java/android/telephony/SignalStrength.java b/telephony/java/android/telephony/SignalStrength.java
index 3128592..05e198f 100644
--- a/telephony/java/android/telephony/SignalStrength.java
+++ b/telephony/java/android/telephony/SignalStrength.java
@@ -568,11 +568,10 @@
int levelLteRsrp = 0;
if (mLteRsrp == -1) levelLteRsrp = 0;
- else if (mLteRsrp >= -90) levelLteRsrp = SIGNAL_STRENGTH_GREAT;
- else if (mLteRsrp >= -100) levelLteRsrp = SIGNAL_STRENGTH_GOOD;
- else if (mLteRsrp >= -110) levelLteRsrp = SIGNAL_STRENGTH_MODERATE;
- else if (mLteRsrp >= -118) levelLteRsrp = SIGNAL_STRENGTH_POOR;
- else levelLteRsrp = 0;
+ else if (mLteRsrp >= -95) levelLteRsrp = SIGNAL_STRENGTH_GREAT;
+ else if (mLteRsrp >= -105) levelLteRsrp = SIGNAL_STRENGTH_GOOD;
+ else if (mLteRsrp >= -115) levelLteRsrp = SIGNAL_STRENGTH_MODERATE;
+ else levelLteRsrp = SIGNAL_STRENGTH_POOR;
if (DBG) log("Lte level: "+levelLteRsrp);
return levelLteRsrp;
