Merge "NFC documentation overhaul." into gingerbread

import android.util.Log;

/**

 * Represents the device's local NFC adapter.

 * Represents the local NFC adapter.

 * <p>

 * Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC

 * adapter for this Android device.

 * <p>

 */

public final class NfcAdapter {

    private static final String TAG = "NFC";

    /**

     * Return true if this NFC Adapter has any features enabled.

     * <p>

     * If this method returns false, then applications should request the user

     * turn on NFC tag discovery in Settings.

     * <p>

     * If this method returns false, the NFC hardware is guaranteed not to

     * perform or respond to any NFC communication.

     *

     * @return true if this NFC Adapter is enabled to discover new tags

     * <p>Application may use this as a helper to suggest that the user

     * should turn on NFC in Settings.

     * <p>If this method returns false, the NFC hardware is guaranteed not to

     * generate or respond to any NFC transactions.

     *

     * @return true if this NFC Adapter has any features enabled

     */

    public boolean isEnabled() {

        try {

    }

    /**

     * Enables foreground dispatching to the given Activity. This will force all NFC Intents that

     * match the given filters to be delivered to the activity bypassing the standard dispatch

     * mechanism. If no IntentFilters are given all the PendingIntent will be invoked for every

     * dispatch Intent.

     * Enable foreground dispatch to the given Activity.

     *

     * <p>This will give give priority to the foreground activity when

     * dispatching a discovered {@link Tag} to an application.

     *

     * <p>Activities must call {@link #disableForegroundDispatch} in

     * their {@link Activity#onPause} callback.

     *

     * <p>a null set of intent filters will cause the forground activity

     * to receive all tags.

     *

     * This method must be called from the main thread.

     * <p>This method must be called from the main thread, and

     * only when the activity is in the foreground (resumed).     *

     *

     * @param activity the Activity to dispatch to

     * @param intent the PendingIntent to start for the dispatch

     * @param filters the IntentFilters to override dispatching for, or null to always dispatch

     * @throws IllegalStateException

     * @throws IllegalStateException if the Activity is not currently in the foreground

     */

    public void enableForegroundDispatch(Activity activity, PendingIntent intent,

            IntentFilter[] filters, String[][] techLists) {

    }

    /**

     * Disables foreground activity dispatching setup with

     * {@link #enableForegroundDispatch}.

     * Disable foreground dispatch to the given activity.

     *

     * <p>This must be called before the Activity returns from

     * it's <code>onPause()</code> or this method will throw an IllegalStateException.

     * <p>After calling {@link #enableForegroundDispatch}, an activity

     * must call this method before its {@link Activity#onPause} callback

     * completes.

     *

     * <p>This method must be called from the main thread.

     *

     * @param activity the Activity to disable dispatch to

     * @throws IllegalStateException if the Activity has already been paused

     */

    public void disableForegroundDispatch(Activity activity) {

        ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,

    }

    /**

     * Enable NDEF message push over P2P while this Activity is in the foreground. For this to

     * function properly the other NFC device being scanned must support the "com.android.npp"

     * NDEF push protocol.

     * Enable NDEF message push over P2P while this Activity is in the foreground.

     *

     * <p>For this to function properly the other NFC device being scanned must

     * support the "com.android.npp" NDEF push protocol. Support for this

     * protocol is currently optional for Android NFC devices.

     *

     * <p>This method must be called from the main thread.

     *

     * <p><em>NOTE</em> While foreground NDEF push is active standard tag dispatch is disabled.

     * Only the foreground activity may receive tag discovered dispatches via

     * {@link #enableForegroundDispatch}.

     *

     * @param activity the foreground Activity

     * @param msg a NDEF Message to push over P2P

     * @throws IllegalStateException if the Activity is not currently in the foreground

     * @throws OperationNotSupportedException if this Android device does not support NDEF push

     */

    public void enableForegroundNdefPush(Activity activity, NdefMessage msg) {

        if (activity == null || msg == null) {

    }

    /**

     * Disables foreground NDEF push setup with

     * {@link #enableForegroundNdefPush}.

     * Disable NDEF message push over P2P.

     *

     * <p>This must be called before the Activity returns from

     * it's <code>onPause()</code> or this method will throw an IllegalStateException.

     * <p>After calling {@link #enableForegroundNdefPush}, an activity

     * must call this method before its {@link Activity#onPause} callback

     * completes.

     *

     * <p>This method must be called from the main thread.

     *

     * @param activity the Foreground activity

     * @throws IllegalStateException if the Activity has already been paused

     * @throws OperationNotSupportedException if this Android device does not support NDEF push

     */

    public void disableForegroundNdefPush(Activity activity) {

        ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,

package android.nfc;

import android.content.Context;

import android.nfc.tech.IsoDep;

import android.nfc.tech.MifareClassic;

import android.nfc.tech.MifareUltralight;

import java.util.Arrays;

/**

 * Represents a (generic) discovered tag.

 * Represents an NFC tag that has been discovered.

 * <p>

 * A tag is a passive NFC element, such as NFC Forum Tag's, MIFARE class Tags,

 * Sony FeliCa Tags, etc.

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

 * <p>

 * Tag's have a type and usually have a UID.

 * 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

 * only the most recent tag object can be successfully used to create a {@link TagTechnology}.

 *

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

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

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

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

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

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

 * <h4>4. Fall-back dispatch</h4>

 * If no application 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>

 * {@link Tag} objects are passed to applications via the {@link NfcAdapter#EXTRA_TAG} extra

 * in {@link NfcAdapter#ACTION_TAG_DISCOVERED} intents. A {@link Tag} object is immutable

 * and represents the state of the tag at the time of discovery. It can be

 * directly queried for its UID and Type, or used to create a {@link TagTechnology} using the

 * static <code>get()</code> methods on the varios tech classes.

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

 * 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

 * range of capabilities available in NFC tags.

 * <p>

 * A {@link Tag} can  be used to create a {@link TagTechnology} only while the tag is in

 * range. If it is removed and then returned to range, then the most recent

 * {@link Tag} object (in {@link NfcAdapter#ACTION_TAG_DISCOVERED}) should be used to create a

 * {@link TagTechnology}.

 * <p>This is an immutable data class. All properties are set at Tag discovery

 * time and calls on this class will retrieve those read-only properties, and

 * not cause any further RF activity or block. Note however that arrays passed to and

 * returned by this class are *not* cloned, so be careful not to modify them.

 */

public final class Tag implements Parcelable {

    /*package*/ final byte[] mId;

    /**

     * Get the Tag Identifier (if it has one).

     * <p>Tag ID is usually a serial number for the tag.

     *

     * @return ID, or null if it does not exist

     * <p>The tag identifier is a low level serial number, used for anti-collision

     * and identification.

     * <p> Most tags have a stable unique identifier

     * (UID), but some tags will generate a random ID every time they are discovered

     * (RID), and there are some tags with no ID at all (the byte array will be zero-sized).

     * <p> The size and format of an ID is specific to the RF technology used by the tag.

     * <p> This function retrieves the ID as determined at discovery time, and does not

     * perform any further RF communication or block.

     * @return ID as byte array, never null

     */

    public byte[] getId() {

        return mId;

    }

    /**

     * Returns technologies present in the tag that this implementation understands,

     * or a zero length array if there are no supported technologies on this tag.

     *

     * The elements of the list are the names of the classes implementing the technology. 

     *

     * Get the technologies available in this tag, as fully qualified class names.

     * <p>

     * A technology is an implementation of the {@link TagTechnology} interface,

     * and can be instantiated by calling the static <code>get(Tag)</code>

     * method on the implementation with this Tag. The {@link TagTechnology}

     * object can then be used to perform advanced, technology-specific operations on a tag.

     * <p>

     * Android defines a mandatory set of technologies that must be correctly

     * enumerated by all Android NFC devices, and an optional

     * set of proprietary technologies.

     * See {@link TagTechnology} for more details.

     * <p>

     * The ordering of the returned array is undefined and should not be relied upon.

     * @return an array of fully-qualified {@link TagTechnology} class-names.

     */

    public String[] getTechList() {

        return mTechStringList;

        return mTagService;

    }

    /**

     * Human-readable description of the tag, for debugging.

     */

    @Override

    public String toString() {

        StringBuilder sb = new StringBuilder("TAG ")

import java.io.IOException;

/**

 * A low-level connection to a {@link Tag} using the ISO-DEP technology, also known as

 * ISO1443-4.

 * Provides access to ISO-DEP (ISO 14443-4) properties and I/O operations on a {@link Tag}.

 *

 * <p>You can acquire this kind of connection with {@link #get}.

 * Use this class to send and receive data with {@link #transceive transceive()}.

 *

 * <p>Applications must implement their own protocol stack on top of

 * {@link #transceive transceive()}.

 *

 * <p class="note"><strong>Note:</strong>

 * Use of this class requires the {@link android.Manifest.permission#NFC}

 * permission.

 * <p>Acquire a {@link IsoDep} object using {@link #get}.

 * <p>The primary ISO-DEP I/O operation is {@link #transceive}. Applications must

 * implement their own protocol stack on top of {@link #transceive}.

 * <p>Tags that enumerate the {@link IsoDep} technology in {@link Tag#getTechList}

 * will also enumerate

 * {@link NfcA} or {@link NfcB} (since IsoDep builds on top of either of these).

 */

public final class IsoDep extends BasicTagTechnology {

    private static final String TAG = "NFC";

    private byte[] mHistBytes = null;

    /**

     * Returns an instance of this tech for the given tag. If the tag doesn't support

     * this tech type null is returned.

     * Get an instance of {@link IsoDep} for the given tag.

     * <p>Does not cause any RF activity and does not block.

     * <p>Returns null if {@link IsoDep} was not enumerated in {@link Tag#getTechList}.

     * This indicates the tag does not support ISO-DEP.

     *

     * @param tag The tag to get the tech from

     * @param tag an ISO-DEP compatible tag

     * @return ISO-DEP object

     */

    public static IsoDep get(Tag tag) {

        if (!tag.hasTech(TagTechnology.ISO_DEP)) return null;

    }

    /**

     * Sets the timeout of an IsoDep transceive transaction in milliseconds.

     * If the transaction has not completed before the timeout,

     * any ongoing {@link #transceive} operation will be

     * aborted and the connection to the tag is lost. This setting is applied

     * only to the {@link Tag} object linked to this technology and will be

     * reset when {@link IsoDep#close} is called.

     * The default transaction timeout is 300 milliseconds.

     * Set the timeout of {@link #transceive} in milliseconds.

     * <p>The timeout only applies to ISO-DEP {@link #transceive}, and is

     * reset to a default value when {@link #close} is called.

     * <p>Setting a longer timeout may be useful when performing

     * transactions that require a long processing time on the tag

     * such as key generation.

     * @param timeout timeout value in milliseconds

     */

    public void setTimeout(int timeout) {

        try {

    }

    /**

     * Return the historical bytes if the tag is using {@link NfcA}, null otherwise.

     * Return the ISO-DEP historical bytes for {@link NfcA} tags.

     * <p>Does not cause any RF activity and does not block.

     * <p>The historical bytes can be used to help identify a tag. They are present

     * only on {@link IsoDep} tags that are based on {@link NfcA} RF technology.

     * If this tag is not {@link NfcA} then null is returned.

     * <p>In ISO 14443-4 terminology, the historical bytes are a subset of the RATS

     * response.

     *

     * @return ISO-DEP historical bytes, or null if this is not a {@link NfcA} tag

     */

    public byte[] getHistoricalBytes() {

        return mHistBytes;

    }

    /**

     * Return the hi layer response bytes if the tag is using {@link NfcB}, null otherwise.

     * Return the higher layer response bytes for {@link NfcB} tags.

     * <p>Does not cause any RF activity and does not block.

     * <p>The higher layer response bytes can be used to help identify a tag.

     * They are present only on {@link IsoDep} tags that are based on {@link NfcB}

     * RF technology. If this tag is not {@link NfcB} then null is returned.

     * <p>In ISO 14443-4 terminology, the higher layer bytes are a subset of the

     * ATTRIB response.

     *

     * @return ISO-DEP historical bytes, or null if this is not a {@link NfcB} tag

     */

    public byte[] getHiLayerResponse() {

        return mHiLayerResponse;

    }

    /**

     * Send data to a tag and receive the response.

     * <p>

     * This method will block until the response is received. It can be canceled

     * with {@link #close}.

     * <p>Requires {@link android.Manifest.permission#NFC} permission.

     * Send raw ISO-DEP data to the tag and receive the response.

     *

     * <p>Applications must only send the INF payload, and not the start of frame and

     * end of frame indicators. Applications do not need to fragment the payload, it

     * will be automatically fragmented and defragmented by {@link #transceive} if

     * it exceeds FSD/FSC limits.

     *

     * <p>This is an I/O operation and will block until complete. It must

     * not be called from the main application thread. A blocked call will be canceled with

     * {@link IOException} if {@link #close} is called from another thread.

     *

     * @param data bytes to send

     * @return bytes received in response

     * @throws IOException if the target is lost or connection closed

     * @param data command bytes to send, must not be null

     * @return response bytes received, will not be null

     * @throws TagLostException if the tag leaves the field

     * @throws IOException if there is an I/O failure, or this operation is canceled

     */

    public byte[] transceive(byte[] data) throws IOException {

        return transceive(data, true);