Merge "More documentation updates for NFC." into gingerbread

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;

    /**

     * 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.

     *

     * This intent is started after {@link #ACTION_NDEF_DISCOVERED} and before

     * {@link #ACTION_TAG_DISCOVERED}

     *

     * If any activities respond to this intent {@link #ACTION_TAG_DISCOVERED} will not be started.

     * 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>

     *   <activity android:name=".nfc.TechFilter" android:label="NFC/TechFilter">

     *       <!-- Add a technology filter -->

     *       <intent-filter>

     *           <action android:name="android.nfc.action.TECH_DISCOVERED" />

     *       </intent-filter>

     *

     *       <meta-data android:name="android.nfc.action.TECH_DISCOVERED"

     *           android:resource="@xml/filter_nfc"

     *       />

     *   </activity>

     * </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".

     *

     * <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}:

     *

     * <pre>

     * <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">

     *     <!-- capture anything using NfcF -->

     *     <tech-list>

     *         <tech>android.nfc.tech.NfcF</tech>

     *     </tech-list>

     *

     *     <!-- OR -->

     *

     *     <!-- capture all MIFARE Classics with NDEF payloads -->

     *     <tech-list>

     *         <tech>android.nfc.tech.NfcA</tech>

     *         <tech>android.nfc.tech.MifareClassic</tech>

     *         <tech>android.nfc.tech.Ndef</tech>

     *     </tech-list>

     * </resources>

     * </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";

    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";

 * <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

 *

 * <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>

 */

     * @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 {