Doc change: Update uses-feature and permissions docs.

Change-Id: I80b45840d83e0622a7b5efeed00a3c659d80ca9b

2 files changed, 802 insertions, 157 deletions

diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd
index 4066daa..45f4a66 100644
--- a/docs/html/guide/topics/manifest/uses-feature-element.jd
+++ b/docs/html/guide/topics/manifest/uses-feature-element.jd
@@ -5,9 +5,9 @@ page.title=<uses-feature>
 
 <dt>syntax:</dt>
 <dd>
-<pre class="stx">&lt;uses-feature android:<a href="#glEsVersion">glEsVersion</a>="<em>integer</em>"
-              android:<a href="#name">name</a>="<em>string</em>"
-              android:<a href="#required">required</a>=["true" | "false"] /&gt;</pre>
+<pre class="stx">&lt;uses-feature android:<a href="#name">name</a>="<em>string</em>"
+              android:<a href="#required">required</a>=["true" | "false"]
+              android:<a href="#glEsVersion">glEsVersion</a>="<em>integer</em>" /&gt;</pre>
 </dd>
 
 <dt>contained in:</dt>
@@ -18,8 +18,8 @@ href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a
   <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> 
   <div id="qv-sub-rule"> 
     <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> 
-    <p style="color:#669999;">Android Market and &lt;uses-feature&gt; elements</p> 
-    <p>Android Market filters the applications that are visible to users, so
+    <p style="color:#669999;">Android Market and <code style="color:#669999;">&lt;uses-feature&gt;</code> elements</p>
+    <p style="margin-top:1em;">Android Market filters the applications that are visible to users, so
 that users can see and download only those applications that are compatible with their
 devices. One of the ways Market filters applications is by feature compatibility.</p>
 
@@ -27,70 +27,82 @@ devices. One of the ways Market filters applications is by feature compatibility
 <code>&lt;uses-feature&gt;</code> elements in each application's manifest, to
 establish the app's feature needs. Market then shows or hides the application to
 each user, based on a comparison with the features available on the user's
-device. For more information, see <a
-href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p>
+device. </p>
 
-<p style="margin-top:1em;">By specifying the features your application requires,
+<p style="margin-top:1em;">By specifying the features that your application requires,
 you enable Android Market to present your application only to users whose
 devices meet the application's feature requirements, rather than presenting it
 to all users. </p>
+
+<p style="margin-top:1em;" class="caution">For important information about how
+Android Market uses features as the basis for filtering, please read <a
+href="#market-feature-filtering">Android Market and Feature-Based Filtering</a>,
+below.</p>
 </div>
 </div>
 
 <dt>description:</dt>
-<dd>This element declares a specific feature used by the application. Android
-provides some features that may not be equally supported by all Android devices.
-In a manner similar to the <a
-href="uses-sdk-element.html">{@code &lt;uses-sdk>}</a> element, this element
-allows an application to specify which device-variable features it uses. For
-example, an application might specify that it requires a camera with auto-focus
-capabilities.</p>
-
-<p>Declaring a {@code &lt;uses-feature>} element is informational only, meaning
+<dd>Declares a single hardware or software feature that is used by the
+application.
+
+<p>The purpose of a <code>&lt;uses-feature&gt;</code> declaration is to inform
+any external entity of the set of hardware and software features on which your
+application depends. The element offers a <code>required</code> attribute that
+lets you specify whether your application requires and cannot function without
+the declared feature, or whether it prefers to have the feature but can function
+without it. Because feature support can vary across Android devices, the
+<code>&lt;uses-feature&gt;</code> element serves an important role in letting an
+application describe the device-variable features that it uses.</p>
+
+<p>The set of available features that your application declares corresponds to
+the set of feature constants made available by the Android {@link
+android.content.pm.PackageManager}, which are listed for
+convenience in the <a href="#features-reference">Features Reference</a> tables
+at the bottom of this document.
+
+<p>You must specify each feature in a separate <code>&lt;uses-feature&gt;</code>
+element, so if your application requires multiple features, it would declare
+multiple <code>&lt;uses-feature&gt;</code> elements. For example, an application
+that requires both Bluetooth and camera features in the device would declare
+these two elements:</p>
+
+<pre>
+&lt;uses-feature android:name="android.hardware.bluetooth" />
+&lt;uses-feature android:name="android.hardware.camera" />
+</pre>
+
+<p>In general, you should always make sure to declare
+<code>&lt;uses-feature&gt;</code> elements for all of the features that your
+application requires.</p>
+
+<p>Declared <code>&lt;uses-feature></code> elements are informational only, meaning
 that the Android system itself does not check for matching feature support on
-the device before installing an application. However, note that other services
+the device before installing an application. However, other services
 (such as Android Market) or applications may check your application's 
-{@code &lt;uses-feature>} declarations as part of handling or interacting 
+<code>&lt;uses-feature></code> declarations as part of handling or interacting
 with your application. For this reason, it's very important that you declare all of
 the features (from the list below) that your application uses. </p>
 
 <p>For some features, there may exist a specfic attribute that allows you to define
 a version of the feature, such as the version of Open GL used (declared with
-<a href="#glEsVersion">{@code glEsVersion}</a>). Other features that either do or do not
+<a href="#glEsVersion"><code>glEsVersion</code></a>). Other features that either do or do not
 exist for a device, such as a camera, are declared using the
-<a href="#name">{@code name}</a> attribute.</p>
+<a href="#name"><code>name</code></a> attribute.</p>
 
-<p>Any software or hardware features that may vary among Android-powered devices
-will be listed on this page among the attributes below. If you see any features
-here that you use in your application, you should include a
-{@code &lt;uses-feature>} element for each one. For example, if your
-application uses the device camera, then you should include the following in
-your {@code AndroidManifest.xml}:</p>
 
-<pre>
-&lt;uses-feature android:name="android.hardware.camera" />
-</pre>
+<p>Although the <code>&lt;uses-feature></code> element is only activated for
+devices running API Level 4 or higher, it is recommended to include these
+elements for all applications, even if the <a href="uses-sdk-element.html#min"><code>minSdkVersion</code></a>
+is "3" or lower. Devices running older versions of the platform will simply
+ignore the element.</p>
 
-<p>If you declare {@code android.hardware.camera} this way, then your application is considered
-compatible with all devices that include a camera. If your application also uses auto-focus
-features, then you also need to include a
-{@code &lt;uses-feature>} element that declares the {@code android.hardware.camera.autofocus}
-feature. Also note that you must still request the {@link android.Manifest.permission#CAMERA
-CAMERA} permission. Requesting the permission grants your application access to the
-appropriate hardware and software, while declaring the features used by
-your application ensures proper device compatibility.</p>
-
-<p>Although the {@code &lt;uses-feature>} element is only activated for devices running 
-API Level 4 or higher, it is safe to include this for applications that declare 
-a <a href="uses-sdk-element.html#min">{@code minSdkVersion}</a> 
-of "3" or lower. Devices running older versions of the platform 
-will simply ignore this element, but newer devices will recognize it and enforce 
-installation restrictions based on whether the device supports the feature.</p>
-
-<p class="note"><strong>Note:</strong>
-For each feature required by your application, you must include a new {@code
-&lt;uses-feature>} element. Multiple features cannot be declared in one 
-instance of this element.</p>
+<p class="note"><strong>Note:</strong> When declaring a feature, remember
+that you must also request permissions as appropriate. For example, you must
+still request the {@link android.Manifest.permission#CAMERA}
+permission before your application can access the camera API. Requesting the
+permission grants your application access to the appropriate hardware and
+software, while declaring the features used by your application ensures proper
+device compatibility.</p>
 
 </dd> 
 
@@ -99,7 +111,35 @@ instance of this element.</p>
 
 <dd>
 <dl class="attr">
-  <dt><a name="glEsVersion"></a>{@code android:glEsVersion}</dt>
+
+  <dt><a name="name"></a><code>android:name</code></dt>
+  <dd>Specifies a single hardware or software feature used by the application,
+as a descriptor string. Valid descriptor values are listed in the <a
+href="#hw-features">Hardware features</a> and <a href="#sw-features">Software
+features</a> tables, below. </dd>
+
+  <dt><a name="required"></a><code>android:required</code></dt>  <!-- added in api level 5 -->
+  <dd>Boolean value that indicates whether the application requires
+  the feature specified in <code>android:name</code>.
+
+<ul>
+<li>When you declare <code>"android:required="true"</code> for a feature,
+you are specifying that the application <em>cannot function, or is not
+designed to function</em>, when the specified feature is not present on the
+device. </li>
+
+<li>When you declare <code>"android:required="false"</code> for a feature, it
+means that the application <em>prefers to use the feature</em> if present on
+the device, but that it <em>is designed to function without the specified
+feature</em>, if necessary. </li>
+
+</ul>
+
+<p>The default value for <code>android:required</code> if not declared is
+<code>"true"</code>.</p>
+  </dd>
+
+  <dt><a name="glEsVersion"></a><code>android:glEsVersion</code></dt>
   <dd>The OpenGL ES version required by the application. The higher 16 bits
 represent the major number and the lower 16 bits represent the minor number. For
 example, to specify OpenGL ES version 2.0, you would set the value as
@@ -125,110 +165,6 @@ only specify the numerically lowest version of OpenGL ES that it requires. (It
 can check at run-time whether a higher level of OpenGL ES is available.)</p>
   </dd>
 
-  <dt><a name="name"></a>{@code android:name}</dt>
-  <dd>The name of a feature required by the application. 
-  The value must be one of the following accepted strings:
-
-  <table>
-    <tr> 
-       <th>Feature</th>
-       <th>Attribute Value</th> 
-       <th>Description</th> 
-    </tr><tr>
-       <td rowspan="2">Camera</td>
-       <td>{@code android.hardware.camera}</td>
-       <td>The application requires a camera.</td> 
-    </tr><tr>
-       <td colspan="2">
-         <strong>Note:</strong> Any application that requests the 
-         {@link android.Manifest.permission#CAMERA} permission but does <em>not</em>
-         declare any camera features with the {@code &lt;uses-feature>} element will be assumed
-         to use all camera features (auto-focus and flash). Thus, the application will not
-         be compatible with devices that do not support all camera features. Please use
-         {@code &lt;uses-feature>} to declare only the camera features that your
-         application does need. For instance, if you request the
-         {@link android.Manifest.permission#CAMERA} permission, but you do not need auto-focus or
-          flash, then declare only the {@code android.hardware.camera} feature&mdash;the other
-          camera features that you do not request will no longer be assumed as required.
-       </td>
-    </tr><tr>
-      <td>Camera auto-focus</td>
-      <td>{@code android.hardware.camera.autofocus}</td>
-      <td>The application requires a camera with auto-focus capability.
-       As a prerequisite, {@code android.hardware.camera} must also be declared
-       with a separate {@code &lt;uses-feature>} element.
-      </td>
-    </tr><tr>
-      <td>Camera flash</td>
-      <td>{@code android.hardware.camera.flash}</td>
-      <td>The application requires a camera with a flash.
-        As a prerequisite, both {@code android.hardware.camera} and {@code
-        android.hardware.camera.autofocus} must also be declared
-        with separate {@code &lt;uses-feature>} elements.
-      </td>
-    </tr><tr>
-      <td>Light sensor</td>
-      <td>{@code android.hardware.sensor.light}</td>
-      <td>The application requires a device with a light sensor.
-      </td>
-    </tr><tr>
-      <td>Live Wallpaper</td>
-      <td>{@code android.software.live_wallpaper}</td>
-      <td>The application uses or provides Live Wallpapers and should be installed only on devices that support Live Wallpapers.
-      </td>
-    </tr><tr>
-      <td>Proximity sensor</td>
-      <td>{@code android.hardware.sensor.proximity}</td>
-      <td>The application requires a device with a proximity sensor.
-      </td>
-    </tr><tr>
-      <td>Multitouch screen</td>
-      <td>{@code android.hardware.touchscreen.multitouch}</td>
-      <td>The application requires a device that supports multitouch.
-      </td>
-    </tr><tr>
-      <td>Telephony</td>
-      <td>{@code android.hardware.telephony}</td>
-      <td>The application requires a device that includes a telephony radio with data
-         communication services.
-      </td>
-    </tr><tr>
-      <td>CDMA telephony</td>
-      <td>{@code android.hardware.telephony.cdma}</td>
-      <td>The application requires a device that includes a CDMA telephony radio. As a
-        prerequisite, {@code android.hardware.telephony} must also be declared
-        with a separate {@code &lt;uses-feature>} element.
-      </td>
-    </tr><tr>
-      <td>GSM telephony</td>
-      <td>{@code android.hardware.telephony.gsm}</td>
-      <td>The application requires a device that includes a GSM telephony radio. As a
-        prerequisite, {@code android.hardware.telephony} must also be declared
-        with a separate {@code &lt;uses-feature>} element.
-      </td>
-    </tr>
-  </table>
-  </dd>
-
-  <dt><a name="required"></a>{@code android:required}</dt>  <!-- added in api level 5 -->
-  <dd>Indicates whether the feature is required by the application. This is
-    {@code true} by default. <strong>You should not use this attribute for most cases.</strong>
-    </p>
-
-    <p>The only situation in which you should set this attribute {@code false} is when your
-    application requests the {@link android.Manifest.permission#CAMERA} permission, but will degrade
-    gracefully and perform without failure if the device does not have a camera. In this situation,
-    you must declare the {@code android.hardware.camera} feature and set the {@code required}
-    attribute {@code false}. This is necessary because the {@link
-    android.Manifest.permission#CAMERA} permission will automatically turn on the requirement for
-    all camera features. So if your application uses this permission but is still compatible with
-    devices without a camera, then you must set the {@code required} attribute {@code false} for
-    {@code android.hardware.camera} or else it will not install on devices without a camera. Note
-    that, while the permission will enable the requirement for <em>all</em> camera features, you
-    only need to off the requirement for the basic camera feature.</p>
-
-  </dd>
-
 </dl>
 </dd>
 
@@ -239,8 +175,680 @@ can check at run-time whether a higher level of OpenGL ES is available.)</p>
 <dt>see also:</dt>
 <dd>
   <ul>
+    <li>{@link android.content.pm.PackageManager}</li>
+    <li>{@link android.content.pm.FeatureInfo}</li>
     <li>{@link android.content.pm.ConfigurationInfo}</li>
+    <li><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code>&lt;uses-permission&gt;</code></a></li>
+    <li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li>
   </ul>
 </dd>
 
 </dl>
+
+
+<h2 id="market-feature-filtering">Android Market and Feature-Based Filtering</h2>
+
+<p>Android Market filters the applications that are visible to users, so that
+users can see and download only those applications that are compatible with
+their devices. One of the ways Market filters applications is by feature
+compatibility.</p>
+
+<p>To determine an application's feature compatibility with a given user's
+device, the Android Market service compares:</p>
+
+<ul>
+<li>Features required by the application &mdash; an application declares features in
+<code>&lt;uses-feature&gt;</code> elements in its manifest <br/>with...</li>
+<li>Features available on the device, in hardware or software &mdash;
+a device reports the features it supports as read-only system properties.</li>
+</ul>
+
+<p>To ensure an accurate comparison of features, the Android Package Manager
+provides a shared set of feature constants that both applications and devices
+use to declare feature requirements and support. The available feature constants
+are listed in the <a href="#features-reference">Features Reference</a> tables at
+the bottom of this document, and in the class documentation for {@link
+android.content.pm.PackageManager}.</p>
+
+<p>When the user launches the Market application, the application queries the
+Package Manager for the list of features available on the device by calling
+{@link android.content.pm.PackageManager#getSystemAvailableFeatures()}. The
+Market application then passes the features list up to the Android Market
+service when establishing the session for the user.</p>
+
+<p>Each time you upload an application to the Android Market Publisher Site,
+Android Market scans the application's manifest file. It looks for
+<code>&lt;uses-feature&gt;</code> elements and evaluates them in combination
+with other elements, in some cases, such as <code>&lt;uses-sdk&gt;</code> and
+<code>&lt;uses-permission&gt;</code> elements. After establishing the
+application's set of required features, it stores that list internally as
+metadata associated with the application <code>.apk</code> and the application
+version. </p>
+
+<p>When a user searches or browses for applications using the Android Market
+application, the service compares the features needed by each application with
+the features available on the user's device. If all of an application's required
+features are present on the device, Android Market allows the user to see the
+application and potentially download it. If any required feature is not
+supported by the device, Android Market filters the application so that it is
+not visible to the user and not available for download. </p>
+
+<p>Because the features you declare in <code>&lt;uses-feature&gt;</code>
+elements directly affect how Android Market filters your application, it's
+important to understand how Android Market evaluates the application's manifest
+and establishes the set of required features. The sections below provide more
+information. </p>
+
+<h3 id="declared">Filtering based on explicitly declared features</h3>
+
+<p>An explicitly declared feature is one that your application declares in a
+<code>&lt;uses-feature&gt;</code> element. The feature declaration can include
+an <code>android:required=["true" | "false"]</code> attribute (if you are
+compiling against API level 5 or higher), which lets you specify whether the
+application absolutely requires the feature and cannot function properly without
+it (<code>"true"</code>), or whether the application prefers to use the feature
+if available, but is designed to run without it (<code>"false"</code>).</p>
+
+<p>Android Market handles explictly declared features in this way: </p>
+
+<ul>
+<li>If a feature is explicitly declared as being required, Android Market adds
+the feature to the list of required features for the application. It then
+filters the application from users on devices that do not provide that feature.
+For example:
+<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="true" /&gt;</pre></li>
+<li>If a feature is explicitly declared as <em>not</em> being required, Android
+Market <em>does not</em> add the feature to the list of required features. For
+that reason, an explicity declared non-required feature is never considered when
+filtering the application. Even if the device does not provide the declared
+feature, Android Market will still consider the application compatible with the
+device and will show it to the user, unless other filtering rules apply. For
+example:
+<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre></li>
+<li>If a feature is explicitly declared, but without an
+<code>android:required</code> attribute, Android Market assumes that the feature
+is required and sets up filtering on it. </li>
+</ul>
+
+<p>In general, if your application is designed to run on Android 1.6 and earlier
+versions, the <code>android:required</code> attribute is not available in the
+API and Android Market assumes that any and all
+<code>&lt;uses-feature&gt;</code> declarations are required. </p>
+
+<p class="note"><strong>Note:</strong> By declaring a feature explicitly and
+including an <code>android:required="false"</code> attribute, you can
+effectively disable all filtering on Android Market for the specified feature.
+</p>
+
+
+<h3 id="implicit">Filtering based on implicit features</h3>
+
+<p>An <em>implicit</em> feature is one that an application requires in order to
+function properly, but which is <em>not</em> declared in a
+<code>&lt;uses-feature&gt;</code> element in the manifest file. Strictly
+speaking, every application should <em>always</em> declare all features that it
+uses or requires, so the absence of a declaration for a feature used by an
+application should be considered an error. However, as a safeguard for users and
+developers, Android Market looks for implicit features in each application and
+sets up filters for those features, just as it would do for an explicitly
+declared feature. </p>
+
+<p>An application might require a feature but not declare it because: </p>
+
+<ul>
+<li>The application was compiled against an older version of the Android library
+(Android 1.5 or earlier) and the <code>&lt;uses-feature&gt;</code> element was
+not available.</li>
+<li>The developer incorrectly assumed that the feature would be present on all
+devices and a declaration was unnecessary.</li>
+<li>The developer omitted the feature declaration accidentally.</li>
+<li>The developer declared the feature explicitly, but the declaration was not
+valid. For example, a spelling error in the <code>&lt;uses-feature&gt;</code>
+element name or an unrecognized string value for the
+<code>android:name</code> attribute would invalidate the feature declaration.
+</li>
+</ul>
+
+<p>To account for the cases above, Android Market attempts to discover an
+application's implied feature requirements by examining <em>other elements</em>
+declared in the manifest file, specifically,
+<code>&lt;uses-permission&gt;</code> elements.</p>
+
+<p>If an application requests hardware-related permissions, Android Market
+<em>assumes that the application uses the underlying hardware features and
+therefore requires those features</em>, even though there might be no
+corresponding to <code>&lt;uses-feature&gt;</code> declarations. For such
+permissions, Android Market adds the underlying hardware features to the
+metadata that it stores for the application and sets up filters for them.</p>
+
+<p>For example, if an application requests the <code>CAMERA</code> permission
+but does not declare a <code>&lt;uses-feature&gt;</code> element for
+<code>android.hardware.camera</code>, Android Market considers that the
+application requires a camera and should not be shown to users whose devices do
+not offer a camera.</p>
+
+<p>If you don't want Android Market to filter based on a specific implied
+feature, you can disable that behavior. To do so, declare the feature explicitly
+in a <code>&lt;uses-feature&gt;</code> element and include an 
+<code>android:required="false"</code> attribute. For example, to disable
+filtering derived from the <code>CAMERA</code> permission, you would declare
+the feature as shown below.</p>
+
+<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>
+
+<p class="caution">It's important to understand that the permissions that you
+request in <code>&lt;uses-permission&gt;</code> elements can directly affect how
+Android Market filters your application. The reference section <a
+href="permissions-features">Permissions that Imply Feature Requirements</a>,
+below, lists the full set of permissions that imply feature requirements and
+therefore trigger filtering.</p>
+
+<h3 id="bt-permission-handling">Special handling for Bluetooth feature</h3>
+
+<p>Android Market applies slightly different rules than described above, when
+determining filtering for Bluetooth.</p>
+
+<p>If an application declares a Bluetooth permission in a
+<code>&lt;uses-permission&gt;</code> element, but does not explicitly declare
+the Bluetooth feature in a <code>&lt;uses-feature&gt;</code> element, Android
+Market checks the version(s) of the Android platform on which the application is
+designed to run, as specified in the <code>&lt;uses-sdk&gt;</code> element. </p>
+
+<p>As shown in the table below, Android Market enables filtering for the
+Bluetooth feature only if the application declares its lowest or targeted
+platform as Android 2.0 (API level 5) or higher. However, note that Android
+market applies the normal rules for filtering when the application explicitly
+declares the Bluetooth feature in a <code>&lt;uses-feature&gt;</code> element.
+</p>
+
+<p class="caption"><strong>Table 1.</strong> How Android Market determines the
+Bluetooth feature requirement for an application that requests a Bluetooth
+permission but does not declare the Bluetooth feature in a
+<code>&lt;uses-feature&gt;</code> element.</p>
+
+<table style="margin-top:1em;">
+<tr>
+<th><nobr>If <code>minSdkVersion</code> is ...</nobr></th>
+<th><nobr>or <code>targetSdkVersion</code> is</nobr></th>
+<th>Result</th>
+</tr>
+<tr>
+<td><nobr>&lt;=4 (or uses-sdk is not declared)</nobr></td>
+<td>&lt;=4</td>
+<td>Android Market <em>will not</em> filter the application from any devices
+based on their reported support for the <code>android.hardware.bluetooth</code>
+feature.</td>
+</tr>
+<tr>
+<td>&lt;=4</td>
+<td>&gt;=5</td>
+<td rowspan="2">Android Market filters the application from any devices that
+do not support the <code>android.hardware.bluetooth</code> feature (including
+older releases).</td>
+</tr>
+<tr>
+<td>&gt;=5</td>
+<td>&gt;=5</td>
+</tr>
+</table>
+
+<p>The examples below illustrate the different filtering effects, based on how
+Android Market handles the Bluetooth feature. </p>
+
+<dl>
+<dt>In first example, an application that is designed to run on older API levels
+declares a Bluetooth permission, but does not declare the Bluetooth feature in a
+<code>&lt;uses-feature&gt;</code> element.</dt>
+<dd><em>Result:</em> Android Market does not filter the application from any device.</dd>
+</dl>
+
+<pre>&lt;manifest ...>
+...
+    &lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+    &lt;uses-sdk android:minSdkVersion="3" />
+...
+&lt;/manifest></pre>
+
+<dl>
+<dt>In the second example, below, the same application also declares a target
+API level of "5". </dt>
+<dd><em>Result:</em> Android Market now assumes that the feature is required and
+will filter the application from all devices that do not report Bluetooth support,
+including devices running older versions of the platform. </dd>
+</dl>
+
+<pre>&lt;manifest ...>
+...
+    &lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+    &lt;uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
+...
+&lt;/manifest></pre>
+
+<dl>
+<dt>Here the same application now specifically declares the Bluetooth feature.</dt>
+<dd><em>Result:</em> Identical to the previous example (filtering is applied).</dd>
+</dl>
+
+<pre>&lt;manifest ...>
+...
+    &lt;uses-feature android:name="android.hardware.bluetooth" />
+    &lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+    &lt;uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
+...
+&lt;/manifest></pre>
+
+<dl>
+<dt>Finally, in the case below, the same application adds an
+<code>android:required="false"</code> attribute.</dt>
+<dd><em>Result:</em> Android Market disables filtering based on Bluetooth
+feature support, for all devices.</dd>
+</dl>
+
+<pre>&lt;manifest ...>
+...
+    &lt;uses-feature android:name="android.hardware.bluetooth" android:required="false" />
+    &lt;uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
+    &lt;uses-sdk android:minSdkVersion="3" android:targetSdkVersion="5" />
+...
+&lt;/manifest></pre>
+
+
+
+<h3>Testing the features required by your application</h3>
+
+<p>You can use the <code>aapt</code> tool, included in the Android SDK, to
+determine how Android Market will filter your application, based on its declared
+features and permissions. To do so, run  <code>aapt</code> with the <code>dump
+badging</code> command. This causes <code>aapt</code> to parse your
+application's manifest and apply the same rules as used by Android Market to
+determine the features that your application requires. </p>
+
+<p>To use the tool, follow these steps: </p>
+
+<ol>
+<li>First, build and export your application as an unsigned <code>.apk</code>.
+If you are developing in Eclipse with ADT, right-click the project and select
+<strong>Android Tools</strong> &gt; <strong>Export Unsigned Application
+Package</strong>. Select a destination filename and path and click
+<strong>OK</strong>. </li>
+<li>Next, locate the <code>aapt</code> tool, if it is not already in your PATH.
+If you are using SDK Tools r7 or earlier, you can find <code>aapt</code> in the
+<code>&lt;<em>SDK</em>&gt;/platforms/android-&lt;<em>platform</em>&gt;/tools/</code> directory.
+<p class="note"><strong>Note:</strong> You must use the version of
+<code>aapt</code> that is provided for the latest platform release available. If
+you do not have the latest platform release, download it using the <a
+href="{@docRoot}sdk/adding-components.html">Android SDK and AVD Manager</a>.
+</p></li>
+<li>Run <code>aapt</code> using this syntax: </li>
+</ol>
+
+<pre>$ aapt dump badging &lt;<em>path_to_exported_.apk</em>&gt;</pre>
+
+<p>Here's an example of the command output for the second Bluetooth example, above: </p>
+
+<pre>$ ./aapt dump badging BTExample.apk
+package: name='com.example.android.btexample' versionCode='' versionName=''
+<strong>uses-permission:'android.permission.BLUETOOTH_ADMIN'</strong>
+<strong>uses-feature:'android.hardware.bluetooth'</strong>
+sdkVersion:'3'
+targetSdkVersion:'5'
+application: label='BT Example' icon='res/drawable/app_bt_ex.png'
+launchable activity name='com.example.android.btexample.MyActivity'label='' icon=''
+uses-feature:'android.hardware.touchscreen'
+main
+supports-screens: 'small' 'normal' 'large'
+locales: '--_--'
+densities: '160'
+</pre>
+
+
+<h2 id=features-reference>Features Reference</h2>
+
+<p>The tables below provide reference information about hardware and software
+features and the permissions that can imply them on Android Market. </p>
+
+<h3 id="hw-features">Hardware features</h3>
+
+<p>The table below describes the hardware feature descriptors supported by the
+most current platform release. To signal that your application uses or requires
+a hardware feature, declare each value in a <code>android:name</code> attribute
+in a separate <code>&lt;uses-feature&gt;</code> element. </p>
+
+  <table>
+    <tr>
+       <th>Feature Type</th>
+       <th>Feature Descriptor</th>
+       <th>Description</th>
+       <th>Comments</th>
+    </tr>
+    <tr>
+       <td>Bluetooth</td>
+       <td><code>android.hardware.bluetooth</td>
+       <td>The application uses Bluetooth radio features in the device.</td>
+<td>
+</td>
+    </tr>
+    <tr>
+       <td rowspan="3">Camera</td>
+       <td><code>android.hardware.camera</code></td>
+       <td>The application uses the device's camera. If the device supports
+           multiple cameras, the application uses the camera that facing
+           away from the screen.</td>
+       <td></td>
+    </tr>
+<tr>
+  <td><code>android.hardware.camera.autofocus</code></td>
+  <td>Subfeature. The application uses the device camera's autofocus capability.</td>
+  <td rowspan="2">If declared with the <code>"android:required="true"</code>
+attribute, these subfeatures implicitly declare the
+<code>android.hardware.camera</code> parent feature. </td>
+</tr>
+<tr>
+  <td><code>android.hardware.camera.flash</code></td>
+  <td>Subfeature. The application uses the device camera's flash.</td>
+</tr>
+
+<tr>
+  <td rowspan="3">Location</td>
+  <td><code>android.hardware.location</code></td>
+  <td>The application uses one or more features on the device for determining
+location, such as GPS location, network location, or cell location.</td>
+  <td></td>
+</tr>
+<tr>
+  <td><code>android.hardware.location.network</code></td>
+  <td>Subfeature. The application uses coarse location coordinates obtained from
+a network-based geolocation system supported on the device.</td>
+  <td rowspan="2">If declared with the <code>"android:required="true"</code>
+attribute, these subfeatures implicitly declare the
+<code>android.hardware.location</code> parent feature. </td>
+</tr>
+<tr>
+  <td><code>android.hardware.location.gps</code></td>
+  <td>Subfeature. The application uses precise location coordinates obtained
+from a Global Positioning System receiver on the device. </td>
+</tr>
+
+<tr>
+  <td rowspan="4">Sensors</td>
+  <td><code>android.hardware.sensor.accelerometer</code></td>
+  <td>The application uses motion readings from an accelerometer on the
+device.</td>
+  <td></td>
+</tr>
+<tr>
+  <td><code>android.hardware.sensor.compass</code></td>
+  <td>The application uses directional readings from a magnetometer (compass) on
+the device.</td>
+  <td></td>
+</tr>
+<tr>
+  <td><code>android.hardware.sensor.light</code></td>
+  <td>The application uses the device's light sensor.</td>
+  <td></td>
+</tr>
+<tr>
+  <td><code>android.hardware.sensor.proximity</code></td>
+  <td>The application uses the device's proximity sensor.</td>
+  <td></td>
+</tr>
+<tr>
+  <td>Microphone</td>
+  <td><code>android.hardware.microphone</code></td>
+  <td>The application uses a microphone on the device.
+  </td>
+  <td></td>
+</tr>
+
+<tr>
+  <td rowspan="3">Telephony</td>
+  <td><code>android.hardware.telephony</code></td>
+  <td>The application uses telephony features on the device, such as telephony
+radio with data communication services.</td>
+  <td></td>
+</tr>
+<tr>
+  <td><code>android.hardware.telephony.cdma</code></td>
+  <td>Subfeature. The application uses CDMA telephony radio features on the
+device. </td>
+  <td rowspan="2">If declared with the <code>"android:required="true"</code>
+attribute, these subfeatures implicitly declare the
+<code>android.hardware.telephony</code> parent feature. </td>
+</tr>
+<tr>
+  <td><code>android.hardware.telephony.gsm</code></td>
+  <td>Subfeature. The application uses GSM telephony radio features on the
+device.</td>
+</tr>
+
+<tr>
+  <td rowspan="3">Touchscreen</td>
+  <td><code>android.hardware.touchscreen</code></td>
+  <td>The application uses touchscreen capabilities on the device.</td>
+  <td></td>
+</tr>
+<tr>
+  <td><code>android.hardware.touchscreen.multitouch</code></td>
+  <td>The application uses basic two-point multitouch capabilities on the device
+screen.</td>
+  <td>If declared with the <code>"android:required="true"</code> attribute, this
+subfeature implicitly declares the <code>android.hardware.touchscreen</code>
+parent feature. </td>
+</tr>
+<tr>
+  <td><code>android.hardware.touchscreen.multitouch.distinct</code></td>
+  <td>Subfeature. The application uses advanced multipoint multitouch
+capabilities on the device screen, such as for tracking two or more points fully
+independently.</td>
+  <td>If declared with the <code>"android:required="true"</code> attribute, this
+subfeature implicitly declares the
+<code>android.hardware.touchscreen.multitouch</code> parent feature. </td>
+</tr>
+
+<tr>
+  <td>Wifi</td>
+  <td><code>android.hardware.wifi</code></td>
+  <td>The application uses 802.11 networking (wifi) features on the device.</td>
+  <td></td>
+</tr>
+
+  </table>
+
+<h3 id="sw-features">Software features</h3>
+
+<p>The table below describes the software feature descriptors supported by the
+most current platform release. To signal that your application uses or requires
+a software feature, declare each value in a <code>android:name</code> attribute
+in a separate <code>&lt;uses-feature&gt;</code> element. </p>
+
+
+  <table>
+    <tr> 
+       <th>Feature</th>
+       <th>Attribute Value</th> 
+       <th>Description</th>
+    </tr>
+    <tr>
+      <td>Live Wallpaper</td>
+      <td><code>android.software.live_wallpaper</code></td>
+      <td>The application uses or provides Live Wallpapers.
+      </td>
+    </tr>
+  </table>
+
+
+<h3 id="permissions">Permissions that Imply Feature Requirements</h3>
+
+<p>Some feature constants listed in the tables above were made available to
+applications <em>after</em> the corresponding API; for example, the
+<code>android.hardware.bluetooth</code> feature was added in Android 2.2 (API
+level 8), but the bluetooth API that it refers to was added in Android 2.0 (API
+level 5). Because of this, some apps were able to use the API before they had
+the ability to declare that they require the API via the
+<code>&lt;uses-feature&gt;</code> system. </p>
+
+<p>To prevent those apps from being made available unintentionally,  Android
+Market assumes that certain hardware-related permissions indicate that the
+underlying hardware features are required by default. For instance, applications
+that use Bluetooth must request the <code>BLUETOOTH</code> permission in a
+<code>&lt;uses-permission&gt;</code> element &mdash; for legacy apps, Android
+Market assumes that the permission declaration means that the underlying
+<code>android.hardware.bluetooth</code> feature is required by the application
+and sets up filtering based on that feature. </p>
+
+<p>The table below lists permissions that imply feature requirements
+equivalent to those declared in <code>&lt;uses-feature&gt;</code> elements. Note
+that <code>&lt;uses-feature&gt;</code> declarations, including any declared
+<code>android:required</code> attribute, always take precedence over features
+implied by the permissions below. </p>
+
+<p>For any of the permissions below, you can disable filtering based on the
+implied feature by explicitly declaring the implied feature explicitly, in a
+<code>&lt;uses-feature&gt;</code> element, with an
+<code>android:required="false"</code> attribute. For example, to disable any
+filtering based on the <code>CAMERA</code> permission, you would add this
+<code>&lt;uses-feature&gt;</code> declaration to the manifest file:</p>
+
+<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="false" /&gt;</pre>
+
+<table id="permissions-features" >
+  <tr> 
+    <th>Category</th>
+    <th>This Permission...</th>
+    <th>Implies This Feature Requirement</th>
+    <!-- <th>Comments</th> -->
+  </tr>
+
+
+<tr>
+  <td rowspan="2">Bluetooth</td>
+  <td><code>BLUETOOTH</code></td>
+  <td><code>android.hardware.bluetooth</code>
+<p>(See <a href="#bt-permission-handling">Special handling for Bluetooth feature</a> for details.)</p></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>BLUETOOTH_ADMIN</code></td>
+  <td><code>android.hardware.bluetooth</code></td>
+<!--  <td></td> -->
+</tr>
+
+<tr>
+  <td>Camera</td>
+  <td><code>CAMERA</code></td>
+  <td><code>android.hardware.camera</code> <em>and</em>
+<br><code>android.hardware.camera.autofocus</code></td>
+<!--  <td></td> -->
+</tr>
+
+<tr>
+  <td rowspan="5">Location</td>
+  <td><code>ACCESS_MOCK_LOCATION</code></td>
+  <td><code>android.hardware.location</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>ACCESS_LOCATION_EXTRA_COMMANDS</code></td>
+  <td><code>android.hardware.location</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>INSTALL_LOCATION_PROVIDER</code></td>
+  <td><code>android.hardware.location</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>ACCESS_COARSE_LOCATION</code></td>
+  <td><code>android.hardware.location.network</code> <em>and</em>
+<br><code>android.hardware.location</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>ACCESS_FINE_LOCATION</code></td>
+  <td><code>android.hardware.location.gps</code> <em>and</em>
+<br><code>android.hardware.location</code></td>
+<!--  <td></td> -->
+</tr>
+
+<tr>
+  <td>Microphone</td>
+  <td><code>RECORD_AUDIO</code></td>
+  <td><code>android.hardware.microphone</code></td>
+<!--  <td></td> -->
+</tr>
+
+<tr>
+  <td rowspan="11">Telephony</td>
+  <td><code>CALL_PHONE</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>CALL_PRIVILEGED</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+
+<tr>
+  <td><code>MODIFY_PHONE_STATE</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>PROCESS_OUTGOING_CALLS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>READ_SMS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>RECEIVE_SMS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>RECEIVE_MMS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>RECEIVE_WAP_PUSH</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>SEND_SMS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>WRITE_APN_SETTINGS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>WRITE_SMS</code></td>
+  <td><code>android.hardware.telephony</code></td>
+<!--  <td></td> -->
+</tr>
+
+<tr>
+  <td rowspan="3">Wifi</td>
+  <td><code>ACCESS_WIFI_STATE</code></td>
+  <td><code>android.hardware.wifi</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>CHANGE_WIFI_STATE</code></td>
+  <td><code>android.hardware.wifi</code></td>
+<!--  <td></td> -->
+</tr>
+<tr>
+  <td><code>CHANGE_WIFI_MULTICAST_STATE</code></td>
+  <td><code>android.hardware.wifi</code></td>
+<!--  <td></td> -->
+</tr>
+</table>
\ No newline at end of file
diff --git a/docs/html/guide/topics/manifest/uses-permission-element.jd b/docs/html/guide/topics/manifest/uses-permission-element.jd
index aec765c..085b9f0 100644
--- a/docs/html/guide/topics/manifest/uses-permission-element.jd
+++ b/docs/html/guide/topics/manifest/uses-permission-element.jd
@@ -2,6 +2,38 @@ page.title=&lt;uses-permission&gt;
 @jd:body
 
 <dl class="xml">
+
+ <div class="sidebox-wrapper"> 
+  <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> 
+  <div id="qv-sub-rule"> 
+    <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> 
+    <p style="color:#669999;"><code style="color:#669999;">&lt;uses-permission&gt;</code> and filtering on Android Market. </p>
+
+<p style="margin-top:1em;">In some cases, the permissions that you request
+through <code>&lt;uses-permission&gt;</code> can affect how
+your application is filtered by Android Market.</p>
+
+<p style="margin-top:1em;">If you request a hardware-related permission &mdash;
+<code>CAMERA</code>, for example &mdash; Android Market assumes that your
+application requires the underlying hardware feature and filters the application
+from devices that do not offer it.</p>
+
+<p style="margin-top:1em;">To control filtering, always explicitly declare
+hardware features in <code>&lt;uses-feature&gt;</code> elements, rather than
+relying on Android Market to "discover" the requirements in
+<code>&lt;uses-permission&gt;</code> elements. Then, if you want to disable
+filtering for a particular feature, you can add a
+<code>android:required="false"</code> attribute to the
+<code>&lt;uses-feature&gt;</code> declaration.</p>
+
+<p style="margin-top:1em;" class="caution">For a list of permissions that imply
+hardware features, see the documentation for the <a
+href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features">
+<code>&lt;uses-feature&gt;</code></a> element.</p>
+</div>
+</div>
+
+
 <dt>syntax:</dt>
 <dd><pre class="stx">&lt;uses-permission android:<a href="#nm">name</a>="<i>string</i>" /&gt;</pre></dd>
 
@@ -10,7 +42,7 @@ page.title=&lt;uses-permission&gt;
 
 <dt>description:</dt>
 <dd>Requests a permission that the application must be granted in 
-order for it to operate correctly.  Permissions are granted when the 
+order for it to operate correctly.  Permissions are granted by the user when the 
 application is installed, not while it's running.
 
 <p>
@@ -38,6 +70,11 @@ a permission name typically includes the package name as a prefix.</dd>
 <dd>API Level 1</dd>
 
 <dt>see also:</dt>
-<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code></dd>
+<dd>
+<ul>
+  <li><code><a href="{@docRoot}guide/topics/manifest/permission-element.html">&lt;permission&gt;</a></code></li>
+  <li><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></code></li>
+</ul>
+</dd>
 
 </dl>