More documentation updates for NFC.

Change-Id: Ie134d4296ee12333e6647ce76126f9767ba1ba34

3 files changed, 115 insertions, 45 deletions

diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index 297f15b..341d348 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -26,8 +26,11 @@ import android.content.Context;
 import android.content.IntentFilter;
 import android.content.pm.IPackageManager;
 import android.content.pm.PackageManager;
+import android.nfc.tech.MifareClassic;
+import android.nfc.tech.Ndef;
+import android.nfc.tech.NfcA;
+import android.nfc.tech.NfcF;
 import android.os.IBinder;
-import android.os.Parcel;
 import android.os.RemoteException;
 import android.os.ServiceManager;
 import android.util.Log;
@@ -44,30 +47,85 @@ public final class NfcAdapter {
 
     /**
      * Intent to start an activity when a tag with NDEF payload is discovered.
-     * If the tag has and NDEF payload this intent is started before
-     * {@link #ACTION_TECH_DISCOVERED}.
      *
-     * If any activities respond to this intent neither
+     * <p>The system inspects the first {@link NdefRecord} in the first {@link NdefMessage} and
+     * looks for a URI, SmartPoster, or MIME record. If a URI or SmartPoster record is found the
+     * intent will contain the URI in its data field. If a MIME record is found the intent will
+     * contain the MIME type in its type field. This allows activities to register
+     * {@link IntentFilter}s targeting specific content on tags. Activities should register the
+     * most specific intent filters possible to avoid the activity chooser dialog, which can
+     * disrupt the interaction with the tag as the user interacts with the screen.
+     *
+     * <p>If the tag has an NDEF payload this intent is started before
+     * {@link #ACTION_TECH_DISCOVERED}. If any activities respond to this intent neither
      * {@link #ACTION_TECH_DISCOVERED} or {@link #ACTION_TAG_DISCOVERED} will be started.
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_NDEF_DISCOVERED = "android.nfc.action.NDEF_DISCOVERED";
 
     /**
-     * Intent to started when a tag is discovered. The data URI is formated as
-     * {@code vnd.android.nfc://tag/} with the path having a directory entry for each technology
-     * in the {@link Tag#getTechList()} is sorted ascending order.
+     * Intent to start an activity when a tag is discovered and activities are registered for the
+     * specific technologies on the tag.
+     *
+     * <p>To receive this intent an activity must include an intent filter
+     * for this action and specify the desired tech types in a
+     * manifest <code>meta-data</code> entry. Here is an example manfiest entry:
+     * <pre>
+     *   &lt;activity android:name=".nfc.TechFilter" android:label="NFC/TechFilter"&gt;
+     *       &lt;!-- Add a technology filter --&gt;
+     *       &lt;intent-filter&gt;
+     *           &lt;action android:name="android.nfc.action.TECH_DISCOVERED" /&gt;
+     *       &lt;/intent-filter&gt;
+     *
+     *       &lt;meta-data android:name="android.nfc.action.TECH_DISCOVERED"
+     *           android:resource="@xml/filter_nfc"
+     *       /&gt;
+     *   &lt;/activity&gt;
+     * </pre>
+     *
+     * <p>The meta-data XML file should contain one or more <code>tech-list</code> entries
+     * each consisting or one or more <code>tech</code> entries. The <code>tech</code> entries refer
+     * to the qualified class name implementing the technology, for example "android.nfc.tech.NfcA".
      *
-     * This intent is started after {@link #ACTION_NDEF_DISCOVERED} and before
-     * {@link #ACTION_TAG_DISCOVERED}
+     * <p>A tag matches if any of the
+     * <code>tech-list</code> sets is a subset of {@link Tag#getTechList() Tag.getTechList()}. Each
+     * of the <code>tech-list</code>s is considered independently and the
+     * activity is considered a match is any single <code>tech-list</code> matches the tag that was
+     * discovered. This provides AND and OR semantics for filtering desired techs. Here is an
+     * example that will match any tag using {@link NfcF} or any tag using {@link NfcA},
+     * {@link MifareClassic}, and {@link Ndef}:
      *
-     * If any activities respond to this intent {@link #ACTION_TAG_DISCOVERED} will not be started.
+     * <pre>
+     * &lt;resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"&gt;
+     *     &lt;!-- capture anything using NfcF --&gt;
+     *     &lt;tech-list&gt;
+     *         &lt;tech&gt;android.nfc.tech.NfcF&lt;/tech&gt;
+     *     &lt;/tech-list&gt;
+     *
+     *     &lt;!-- OR --&gt;
+     *
+     *     &lt;!-- capture all MIFARE Classics with NDEF payloads --&gt;
+     *     &lt;tech-list&gt;
+     *         &lt;tech&gt;android.nfc.tech.NfcA&lt;/tech&gt;
+     *         &lt;tech&gt;android.nfc.tech.MifareClassic&lt;/tech&gt;
+     *         &lt;tech&gt;android.nfc.tech.Ndef&lt;/tech&gt;
+     *     &lt;/tech-list&gt;
+     * &lt;/resources&gt;
+     * </pre>
+     *
+     * <p>This intent is started after {@link #ACTION_NDEF_DISCOVERED} and before
+     * {@link #ACTION_TAG_DISCOVERED}. If any activities respond to {@link #ACTION_NDEF_DISCOVERED}
+     * this intent will not be started. If any activities respond to this intent
+     * {@link #ACTION_TAG_DISCOVERED} will not be started.
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_TECH_DISCOVERED = "android.nfc.action.TECH_DISCOVERED";
 
     /**
      * Intent to start an activity when a tag is discovered.
+     *
+     * <p>This intent will not be started when a tag is discovered if any activities respond to
+     * {@link #ACTION_NDEF_DISCOVERED} or {@link #ACTION_TECH_DISCOVERED} for the current tag. 
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_TAG_DISCOVERED = "android.nfc.action.TAG_DISCOVERED";
@@ -79,17 +137,23 @@ public final class NfcAdapter {
     public static final String ACTION_TAG_LEFT_FIELD = "android.nfc.action.TAG_LOST";
 
     /**
-     * Mandatory Tag extra for the ACTION_TAG intents.
+     * Mandatory extra containing the {@link Tag} that was discovered for the
+     * {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and
+     * {@link #ACTION_TAG_DISCOVERED} intents.
      */
     public static final String EXTRA_TAG = "android.nfc.extra.TAG";
 
     /**
-     * Optional NdefMessage[] extra for the ACTION_TAG intents.
+     * Optional extra containing an array of {@link NdefMessage} present on the discovered tag for
+     * the {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and
+     * {@link #ACTION_TAG_DISCOVERED} intents.
      */
     public static final String EXTRA_NDEF_MESSAGES = "android.nfc.extra.NDEF_MESSAGES";
 
     /**
-     * Optional byte[] extra for the tag identifier.
+     * Optional extra containing a byte array containing the ID of the discovered tag for
+     * the {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and
+     * {@link #ACTION_TAG_DISCOVERED} intents.
      */
     public static final String EXTRA_ID = "android.nfc.extra.ID";
 
diff --git a/core/java/android/nfc/Tag.java b/core/java/android/nfc/Tag.java
index 2305fb9..b676975 100644
--- a/core/java/android/nfc/Tag.java
+++ b/core/java/android/nfc/Tag.java
@@ -38,9 +38,9 @@ import java.util.Arrays;
  * <p>
  * {@link Tag} is an immutable object that represents the state of a NFC tag at
  * the time of discovery. It can be used as a handle to {@link TagTechnology} classes
- * to perform advanced operations, or directly queried for its ID ({@link #getId} and the
- * set of technologies it contains ({@link #getTechList}). Arrays passed to and
- * returned by this class are *not* cloned, so be careful not to modify them.
+ * to perform advanced operations, or directly queried for its ID via {@link #getId} and the
+ * set of technologies it contains via {@link #getTechList}. Arrays passed to and
+ * returned by this class are <em>not</em> cloned, so be careful not to modify them.
  * <p>
  * A new tag object is created every time a tag is discovered (comes into range), even
  * if it is the same physical tag. If a tag is removed and then returned into range, then
@@ -48,53 +48,60 @@ import java.util.Arrays;
  *
  * <h3>Tag Dispatch</h3>
  * When a tag is discovered, a {@link Tag} object is created and passed to a
- * single application via the {@link NfcAdapter#EXTRA_TAG} extra in a
- * {@link Context#startActivity} {@link android.content.Intent}. A four stage dispatch is used to select the
- * most appropriate application to handle the tag. The Android OS executes each stage in order,
- * and completes dispatch as soon as a single matching application is found. If there are multiple
- * matching applications found at any one stage then the Android Activity Chooser dialog is shown
- * to allow the user to select the application.
+ * single activity via the {@link NfcAdapter#EXTRA_TAG} extra in an
+ * {@link android.content.Intent} via {@link Context#startActivity}. A four stage dispatch is used
+ * to select the
+ * most appropriate activity to handle the tag. The Android OS executes each stage in order,
+ * and completes dispatch as soon as a single matching activity is found. If there are multiple
+ * matching activities found at any one stage then the Android activity chooser dialog is shown
+ * to allow the user to select the activity to receive the tag.
+ *
+ * <p>The Tag dispatch mechanism was designed to give a high probability of dispatching
+ * a tag to the correct activity without showing the user an activity chooser dialog.
+ * This is important for NFC interactions because they are very transient -- if a user has to
+ * move the Android device to choose an application then the connection will likely be broken.
+ *
  * <h4>1. Foreground activity dispatch</h4>
- * A foreground activity that has called {@link NfcAdapter#enableForegroundDispatch} is
- * given priority. See the documentation on {#link NfcAdapter#enableForegroundDispatch} for
+ * A foreground activity that has called
+ * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} is
+ * given priority. See the documentation on
+ * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} for
  * its usage.
  * <h4>2. NDEF data dispatch</h4>
- * If the tag contains NDEF data, then {@link Context#startActivity} is called with
- * {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and a data URI determined from the
- * first NDEF Record in the first NDEF Message in the Tag. This allows NDEF tags to be given
- * priority dispatch to applications that can handle the content.
+ * If the tag contains NDEF data the system inspects the first {@link NdefRecord} in the first
+ * {@link NdefMessage}. If the record is a URI, SmartPoster, or MIME data
+ * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_NDEF_DISCOVERED}. For URI
+ * and SmartPoster records the URI is put into the intent's data field. For MIME records the MIME
+ * type is put in the intent's type field. This allows activities to register to be launched only
+ * when data they know how to handle is present on a tag. This is the preferred method of handling
+ * data on a tag since NDEF data can be stored on many types of tags and doesn't depend on a
+ * specific tag technology. 
  * See {@link NfcAdapter#ACTION_NDEF_DISCOVERED} for more detail. If the tag does not contain
- * NDEF data, or if no application is registered
- * for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI then dispatch moves
- * to stage 3.
+ * NDEF data, or if no activity is registered
+ * for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI or MIME type then dispatch
+ * moves to stage 3.
  * <h4>3. Tag Technology dispatch</h4>
  * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_TECH_DISCOVERED} to
- * dispatch the tag to an application that can handle the technologies present on the tag.
+ * dispatch the tag to an activity that can handle the technologies present on the tag.
  * Technologies are defined as sub-classes of {@link TagTechnology}, see the package
- * {@link android.nfc.tech}. The Android OS looks for an application that can handle one or
- * more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED for more detail.
+ * {@link android.nfc.tech}. The Android OS looks for an activity that can handle one or
+ * more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED} for more detail.
  * <h4>4. Fall-back dispatch</h4>
- * If no application has been matched, then {@link Context#startActivity} is called with
+ * If no activity has been matched then {@link Context#startActivity} is called with
  * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. This is intended as a fall-back mechanism.
  * See {@link NfcAdapter#ACTION_TAG_DISCOVERED}.
  *
- * <p>
- * <i>The Tag dispatch mechanism was designed to give a high probability of dispatching
- * a tag to the correct application without showing the user an Application Chooser dialog.
- * This is important for NFC interactions because they are very transient - if a user has to
- * move the Android device to choose an application then the connection is broken.</i>
- *
  * <h3>NFC Tag Background</h3>
  * An NFC tag is a passive NFC device, powered by the NFC field of this Android device while
- * it is in range. Tag's can come in many forms, such as stickers, cards, key fob, or
+ * it is in range. Tag's can come in many forms, such as stickers, cards, key fobs, or
  * even embedded in a more sophisticated device.
  * <p>
  * Tags can have a wide range of capabilities. Simple tags just offer read/write semantics,
  * and contain some one time
  * programmable areas to make read-only. More complex tags offer math operations
  * and per-sector access control and authentication. The most sophisticated tags
- * contain operating environments such as Javacard, allowing complex interactions with the
- * applets executing on the tag. Use {@link TagTechnology} classes to access a broad
+ * contain operating environments allowing complex interactions with the
+ * code executing on the tag. Use {@link TagTechnology} classes to access a broad
  * range of capabilities available in NFC tags.
  * <p>
  */
diff --git a/core/java/android/nfc/tech/Ndef.java b/core/java/android/nfc/tech/Ndef.java
index 0467473..4ea9f8a 100644
--- a/core/java/android/nfc/tech/Ndef.java
+++ b/core/java/android/nfc/tech/Ndef.java
@@ -137,7 +137,6 @@ public final class Ndef extends BasicTagTechnology {
      * @param tag an MIFARE Classic compatible tag
      * @return MIFARE Classic object
      */
-
     public static Ndef get(Tag tag) {
         if (!tag.hasTech(TagTechnology.NDEF)) return null;
         try {