NFC card emulation API docs.

import java.util.HashMap;

import java.util.List;

/**

 * This class can be used to query the state of

 * NFC card emulation services.

 *

 * For a general introduction into NFC card emulation,

 * please read the <a href="{@docRoot}guide/topics/nfc/ce.html">

 * NFC card emulation developer guide</a>.</p>

 *

 * <p class="note">Use of this class requires the

 * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present

 * on the device.

 */

public final class CardEmulation {

    static final String TAG = "CardEmulation";

            "android.nfc.cardemulation.action.ACTION_CHANGE_DEFAULT";

    /**

     * The category extra for {@link #ACTION_CHANGE_DEFAULT}

     * The category extra for {@link #ACTION_CHANGE_DEFAULT}.

     *

     * @see #ACTION_CHANGE_DEFAULT

     */

    public static final String EXTRA_CATEGORY = "category";

    /**

     * The ComponentName object passed in as a parcelable

     * extra for {@link #ACTION_CHANGE_DEFAULT}

     * The service {@link ComponentName} object passed in as an

     * extra for {@link #ACTION_CHANGE_DEFAULT}.

     *

     * @see #ACTION_CHANGE_DEFAULT

     */

    public static final String EXTRA_SERVICE_COMPONENT = "component";

    /**

     * The payment category can be used to indicate that an AID

     * represents a payment application.

     * Category used for NFC payment services.

     */

    public static final String CATEGORY_PAYMENT = "payment";

    /**

     * If an AID group does not contain a category, or the

     * specified category is not defined by the platform version

     * that is parsing the AID group, all AIDs in the group will

     * automatically be categorized under the {@link #CATEGORY_OTHER}

     * category.

     * Category that can be used for all other card emulation

     * services.

     */

    public static final String CATEGORY_OTHER = "other";

     * Return value for {@link #getSelectionModeForCategory(String)}.

     *

     * <p>In this mode, the user has set a default service for this

     *    AID category. If a remote reader selects any of the AIDs

     *    category.

     *

     * <p>When using ISO-DEP card emulation with {@link HostApduService}

     *    or {@link OffHostApduService}, if a remote NFC device selects

     *    any of the Application IDs (AIDs)

     *    that the default service has registered in this category,

     *    that service will automatically be bound to to handle

     *    the transaction.

     *

     * <p>There are still cases where a service that is

     *    not the default for a category can selected:

     *    <p>

     *    If a remote reader selects an AID in this category

     *    that is not handled by the default service, and there is a set

     *    of other services {S} that do handle this AID, the

     *    user is asked if he wants to use any of the services in

     *    {S} instead.

     *    <p>

     *    As a special case, if the size of {S} is one, containing a single service X,

     *    and all AIDs X has registered in this category are not

     *    registered by any other service, then X will be

     *    selected automatically without asking the user.

     *    <p>Example:

     *    <ul>

     *    <li>Service A registers AIDs "1", "2" and "3" in the category

     *    <li>Service B registers AIDs "3" and "4" in the category

     *    <li>Service C registers AIDs "5" and "6" in the category

     *    </ul>

     *    In this case, the following will happen when service A

     *    is the default:

     *    <ul>

     *    <li>Reader selects AID "1", "2" or "3": service A is invoked automatically

     *    <li>Reader selects AID "4": the user is asked to confirm he

     *        wants to use service B, because its AIDs overlap with service A.

     *    <li>Reader selects AID "5" or "6": service C is invoked automatically,

     *        because all AIDs it has asked for are only registered by C,

     *        and there is no overlap.

     *    </ul>

     *

     */

    public static final int SELECTION_MODE_PREFER_DEFAULT = 0;

    /**

     * Return value for {@link #getSelectionModeForCategory(String)}.

     *

     * <p>In this mode, whenever an AID of this category is selected,

     *    the user is asked which service he wants to use to handle

     * <p>In this mode, when using ISO-DEP card emulation with {@link HostApduService}

     *    or {@link OffHostApduService}, whenever an Application ID (AID) of this category

     *    is selected, the user is asked which service he wants to use to handle

     *    the transaction, even if there is only one matching service.

     */

    public static final int SELECTION_MODE_ALWAYS_ASK = 1;

    /**

     * Return value for {@link #getSelectionModeForCategory(String)}.

     *

     * <p>In this mode, the user will only be asked to select a service

     *    if the selected AID has been registered by multiple applications.

     * <p>In this mode, when using ISO-DEP card emulation with {@link HostApduService}

     *    or {@link OffHostApduService}, the user will only be asked to select a service

     *    if the Application ID (AID) selected by the reader has been registered by multiple

     *    services. If there is only one service that has registered for the AID,

     *    that service will be invoked directly.

     */

    public static final int SELECTION_MODE_ASK_IF_CONFLICT = 2;

    static boolean sIsInitialized = false;

    static HashMap<Context, CardEmulation> sCardEmus = new HashMap();

    static HashMap<Context, CardEmulation> sCardEmus = new HashMap<Context, CardEmulation>();

    static INfcCardEmulation sService;

    final Context mContext;

        sService = service;

    }

    /**

     * Helper to get an instance of this class.

     *

     * @param adapter A reference to an NfcAdapter object.

     * @return

     */

    public static synchronized CardEmulation getInstance(NfcAdapter adapter) {

        if (adapter == null) throw new NullPointerException("NfcAdapter is null");

        Context context = adapter.getContext();

     * the default service to handle a card emulation category.

     *

     * <p>Note that if {@link #getSelectionModeForCategory(String)}

     * returns {@link #SELECTION_MODE_ALWAYS_ASK}, this method will always

     * return false.

     * returns {@link #SELECTION_MODE_ALWAYS_ASK} or {@link #SELECTION_MODE_ASK_IF_CONFLICT},

     * this method will always return false. That is because in these

     * selection modes a default can't be set at the category level. For categories where

     * the selection mode is {@link #SELECTION_MODE_ALWAYS_ASK} or

     * {@link #SELECTION_MODE_ASK_IF_CONFLICT}, use

     * {@link #isDefaultServiceForAid(ComponentName, String)} to determine whether a service

     * is the default for a specific AID.

     *

     * @param service The ComponentName of the service

     * @param category The category

     * @return whether service is currently the default service for the category.

     *

     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.

     */

    public boolean isDefaultServiceForCategory(ComponentName service, String category) {

        try {

     *

     * @param service The ComponentName of the service

     * @param aid The ISO7816-4 Application ID

     * @return

     * @return whether the service is the default handler for the specified AID

     *

     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.

     */

    public boolean isDefaultServiceForAid(ComponentName service, String aid) {

        try {

    }

    /**

     * Returns the application selection mode for the passed in category.

     * Returns the service selection mode for the passed in category.

     * Valid return values are:

     * <p>{@link #SELECTION_MODE_PREFER_DEFAULT} the user has requested a default

     *    application for this category, which will be preferred.

     *    service for this category, which will be preferred.

     * <p>{@link #SELECTION_MODE_ALWAYS_ASK} the user has requested to be asked

     *    every time what app he would like to use in this category.

     *    every time what service he would like to use in this category.

     * <p>{@link #SELECTION_MODE_ASK_IF_CONFLICT} the user will only be asked

     *    to pick a service if there is a conflict.

     * @param category The category, for example {@link #CATEGORY_PAYMENT}

     * @return

     * @return the selection mode for the passed in category

     */

    public int getSelectionModeForCategory(String category) {

        if (CATEGORY_PAYMENT.equals(category)) {

            }

        }

    }

    /**

     * @hide

     */

import android.annotation.SdkConstant.SdkConstantType;

import android.app.Service;

import android.content.Intent;

import android.content.pm.PackageManager;

import android.os.Bundle;

import android.os.Handler;

import android.os.IBinder;

import android.util.Log;

/**

 * <p>A convenience class that can be extended to implement

 * a service that processes ISO7816-4 commands on top of

 * the ISO14443-4 / IsoDep protocol (T=CL).

 * <p>HostApduService is a convenience {@link Service} class that can be

 * extended to emulate an NFC card inside an Android

 * service component.

 *

 * <p>To tell the platform which ISO7816 application ID (AIDs)

 * are implemented by this service, a {@link #SERVICE_META_DATA}

 * <div class="special reference">

 * <h3>Developer Guide</h3>

 * For a general introduction into the topic of card emulation,

 * please read the <a href="{@docRoot}guide/topics/nfc/ce.html">

 * NFC card emulation developer guide.</a></p>

 * </div>

 *

 * <h3>NFC Protocols</h3>

 * <p>Cards emulated by this class are based on the NFC-Forum ISO-DEP

 * protocol (based on ISO/IEC 14443-4) and support processing

 * command Application Protocol Data Units (APDUs) as

 * defined in the ISO/IEC 7816-4 specification.

 *

 * <h3>Service selection</h3>

 * <p>When a remote NFC device wants to talk to your

 * service, it sends a so-called

 * "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification.

 * The AID is an application identifier defined in ISO/IEC 7816-4.

 *

 * <p>The registration procedure for AIDs is defined in the

 * ISO/IEC 7816-5 specification. If you don't want to register an

 * AID, you are free to use AIDs in the proprietary range:

 * bits 8-5 of the first byte must each be set to '1'. For example,

 * "0xF00102030405" is a proprietary AID. If you do use proprietary

 * AIDs, it is recommended to choose an AID of at least 6 bytes,

 * to reduce the risk of collisions with other applications that

 * might be using proprietary AIDs as well.

 *

 * <h3>AID groups</h3>

 * <p>In some cases, a service may need to register multiple AIDs

 * to implement a certain application, and it needs to be sure

 * that it is the default handler for all of these AIDs (as opposed

 * to some AIDs in the group going to another service).

 *

 * <p>An AID group is a list of AIDs that should be considered as

 * belonging together by the OS. For all AIDs in an AID group, the

 * OS will guarantee one of the following:

 * <ul>

 * <li>All AIDs in the group are routed to this service

 * <li>No AIDs in the group are routed to this service

 * </ul>

 * In other words, there is no in-between state, where some AIDs

 * in the group can be routed to this service, and some to another.

 * <h3>AID groups and categories</h3>

 * <p>Each AID group can be associated with a category. This allows

 * the Android OS to classify services, and it allows the user to

 * set defaults at the category level instead of the AID level.

 *

 * <p>You can use

 * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)}

 * to determine if your service is the default handler for a category.

 *

 * <p>In this version of the platform, the only known categories

 * are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}.

 * AID groups without a category, or with a category that is not recognized

 * by the current platform version, will automatically be

 * grouped into the {@link CardEmulation#CATEGORY_OTHER} category.

 * <h3>Service AID registration</h3>

 * <p>To tell the platform which AIDs groups

 * are requested by this service, a {@link #SERVICE_META_DATA}

 * entry must be included in the declaration of the service. An

 * example of such a service declaration is shown below:

 * <pre> &lt;service android:name=".MyHostApduService"&gt;

 * example of a HostApduService manifest declaration is shown below:

 * <pre> &lt;service android:name=".MyHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"&gt;

 *     <intent-filter>

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

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

 *     </intent-filter>

 *     <meta-data android:name="android.nfc.HostApduService" android:resource="@xml/apduservice.xml"/>

 *     <meta-data android:name="android.nfc.cardemulation.host_apdu_ervice" android:resource="@xml/apduservice"/>

 * &lt;/service&gt;</pre>

 * <p>For more details refer to {@link #SERVICE_META_DATA},

 * <code>&lt;{@link android.R.styleable#HostApduService host-apdu-service}&gt;</code>,

 * <code>&lt;{@link android.R.styleable#AidGroup aid-group}&gt;</code> and

 * <code>&lt;{@link android.R.styleable#AidFilter aid-filter}&gt;</code>.

 * <p class="note">The Android platform currently only supports a single

 * logical channel.

 *

 * This meta-data tag points to an apduservice.xml file.

 * An example of this file with a single AID group declaration is shown below:

 * <pre>

 * <host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"

 *           android:description="@string/servicedesc" android:requireDeviceUnlock="false">

 *       <aid-group android:description="@string/aiddescription" android:category="other">

 *           <aid-filter android:name="F0010203040506"/>

 *           <aid-filter android:name="F0394148148100"/>

 *       </aid-group>

 * </host-apdu-service>

 * </pre>

 *

 * <p>The {@link android.R.styleable#HostApduService &lt;host-apdu-service&gt;} is required

 * to contain a

 * {@link android.R.styleable#HostApduService_description <android:description>}

 * attribute that contains a user-friendly description of the service that may be shown in UI.

 * The

 * {@link android.R.styleable#HostApduService_requireDeviceUnlock <requireDeviceUnlock>}

 * attribute can be used to specify that the device must be unlocked before this service

 * can be invoked to handle APDUs.

 * <p>The {@link android.R.styleable#HostApduService &lt;host-apdu-service&gt;} must

 * contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags.

 * Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or

 * more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which

 * contains a single AID. The AID must be specified in hexadecimal format, and contain

 * an even number of characters.

 * <h3>AID conflict resolution</h3>

 * Multiple HostApduServices may be installed on a single device, and the same AID

 * can be registered by more than one service. The Android platform resolves AID

 * conflicts depending on which category an AID belongs to. Each category may

 * have a different conflict resolution policy. For example, for some categories

 * the user may be able to select a default service in the Android settings UI.

 * For other categories, to policy may be to always ask the user which service

 * is to be invoked in case of conflict.

 *

 * To query the conflict resolution policy for a certain category, see

 * {@link CardEmulation#getSelectionModeForCategory(String)}.

 *

 * <h3>Data exchange</h3>

 * <p>Once the platform has resolved a "SELECT AID" command APDU to a specific

 * service component, the "SELECT AID" command APDU and all subsequent

 * command APDUs will be sent to that service through

 * {@link #processCommandApdu(byte[], Bundle)}, until either:

 * <ul>

 * <li>The NFC link is broken</li>

 * <li>A "SELECT AID" APDU is received which resolves to another service</li>

 * </ul>

 * These two scenarios are indicated by a call to {@link #onDeactivated(int)}.

 *

 * <p class="note">Use of this class requires the

 * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present

 * on the device.

 *

 */

public abstract class HostApduService extends Service {

    /**

     * The {@link Intent} that must be declared as handled by the service.

     * The {@link Intent} action that must be declared as handled by the service.

     */

    @SdkConstant(SdkConstantType.SERVICE_ACTION)

    public static final String SERVICE_INTERFACE =

     * If you cannot return a response APDU immediately, return null

     * and use the {@link #sendResponseApdu(byte[])} method later.

     *

     * @param commandApdu The APDU that received from the remote device

     * @param commandApdu The APDU that was received from the remote device

     * @param extras A bundle containing extra data. May be null.

     * @return a byte-array containing the response APDU, or null if no

     *         response APDU can be sent at this point.

import android.annotation.SdkConstant.SdkConstantType;

import android.app.Service;

import android.content.Intent;

import android.content.pm.PackageManager;

import android.os.IBinder;

/**

 * <p>A convenience class that can be extended to implement

 * a service that registers ISO7814-4 AIDs that reside off-host,

 * for example on an embedded secure element or UICC.

 * <p>OffHostApduService is a convenience {@link Service} class that can be

 * extended to describe one or more NFC applications that are residing

 * off-host, for example on an embedded secure element or a UICC.

 *

 * <div class="special reference">

 * <h3>Developer Guide</h3>

 * For a general introduction into the topic of card emulation,

 * please read the <a href="{@docRoot}guide/topics/nfc/ce.html">

 * NFC card emulation developer guide.</a></p>

 * </div>

 *

 * <h3>NFC Protocols</h3>

 * <p>Off-host applications represented by this class are based on the NFC-Forum ISO-DEP

 * protocol (based on ISO/IEC 14443-4) and support processing

 * command Application Protocol Data Units (APDUs) as

 * defined in the ISO/IEC 7816-4 specification.

 *

 * <h3>Service selection</h3>

 * <p>When a remote NFC device wants to talk to your

 * off-host NFC application, it sends a so-called

 * "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification.

 * The AID is an application identifier defined in ISO/IEC 7816-4.

 *

 * <p>The registration procedure for AIDs is defined in the

 * ISO/IEC 7816-5 specification. If you don't want to register an

 * AID, you are free to use AIDs in the proprietary range:

 * bits 8-5 of the first byte must each be set to '1'. For example,

 * "0xF00102030405" is a proprietary AID. If you do use proprietary

 * AIDs, it is recommended to choose an AID of at least 6 bytes,

 * to reduce the risk of collisions with other applications that

 * might be using proprietary AIDs as well.

 *

 * <h3>AID groups</h3>

 * <p>In some cases, an off-host environment may need to register multiple AIDs

 * to implement a certain application, and it needs to be sure

 * that it is the default handler for all of these AIDs (as opposed

 * to some AIDs in the group going to another service).

 *

 * <p>An AID group is a list of AIDs that should be considered as

 * belonging together by the OS. For all AIDs in an AID group, the

 * OS will guarantee one of the following:

 * <ul>

 * <li>All AIDs in the group are routed to the off-host execution environment

 * <li>No AIDs in the group are routed to the off-host execution environment

 * </ul>

 * In other words, there is no in-between state, where some AIDs

 * in the group can be routed to this off-host execution environment,

 * and some to another or a host-based {@link HostApduService}.

 * <h3>AID groups and categories</h3>

 * <p>Each AID group can be associated with a category. This allows

 * the Android OS to classify services, and it allows the user to

 * set defaults at the category level instead of the AID level.

 *

 * <p>You can use

 * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)}

 * to determine if your off-host service is the default handler for a category.

 *

 * <p>In this version of the platform, the only known categories

 * are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}.

 * AID groups without a category, or with a category that is not recognized

 * by the current platform version, will automatically be

 * grouped into the {@link CardEmulation#CATEGORY_OTHER} category.

 *

 * <h3>Service AID registration</h3>

 * <p>To tell the platform which AIDs

 * reside off-host and are managed by this service, a {@link #SERVICE_META_DATA}

 * entry must be included in the declaration of the service. An

 * example of a OffHostApduService manifest declaration is shown below:

 * <pre> &lt;service android:name=".MyOffHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"&gt;

 *     <intent-filter>

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

 *     </intent-filter>

 *     <meta-data android:name="android.nfc.cardemulation.off_host_apdu_ervice" android:resource="@xml/apduservice"/>

 * &lt;/service&gt;</pre>

 *

 * This meta-data tag points to an apduservice.xml file.

 * An example of this file with a single AID group declaration is shown below:

 * <pre>

 * <offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"

 *           android:description="@string/servicedesc">

 *       <aid-group android:description="@string/subscription" android:category="other">

 *           <aid-filter android:name="F0010203040506"/>

 *           <aid-filter android:name="F0394148148100"/>

 *       </aid-group>

 * </offhost-apdu-service>

 * </pre>

 *

 * <p>The {@link android.R.styleable#OffHostApduService &lt;offhost-apdu-service&gt;} is required

 * to contain a

 * {@link android.R.styleable#OffHostApduService_description <android:description>}

 * attribute that contains a user-friendly description of the service that may be shown in UI.

 *

 * <p>The {@link android.R.styleable#OffHostApduService &lt;offhost-apdu-service&gt;} must

 * contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags.

 * Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or

 * more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which

 * contains a single AID. The AID must be specified in hexadecimal format, and contain

 * an even number of characters.

 *

 * <p>This registration will allow the service to be included

 * as an option for handling these AIDs on non-host execution

 * environments. The Operating System will take care of correctly

 * routing the AIDs, based on which service the user has selected

 * to be the handler for an AID.

 * as an option for being the default handler for categories.

 * The Android OS will take care of correctly

 * routing the AIDs to the off-host execution environment,

 * based on which service the user has selected to be the handler for a certain category.

 *

 * <p>The service may define additional actions outside of the

 * Android namespace that provide further interaction with

 * the off-host execution environment.

 *

 * <p>To tell the platform which ISO7816 application ID (AIDs)

 * are present and handled by the app containing this service,

 * a {@link #SERVICE_META_DATA} entry must be included in the declaration

 * of the service. An example of such a service declaration is shown below:

 * <pre> &lt;service android:name=".MyOffHostApduService"&gt;

 *     <intent-filter>

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

 *     </intent-filter>

 *     <meta-data android:name="android.nfc.OffHostApduService" android:resource="@xml/apduservice.xml"/>

 * &lt;/service&gt;</pre>

 * <p>For more details refer to {@link #SERVICE_META_DATA},

 * <code>&lt;{@link android.R.styleable#OffHostApduService offhost-apdu-service}&gt;</code>,

 * <code>&lt;{@link android.R.styleable#AidGroup aid-group}&gt;</code> and

 * <code>&lt;{@link android.R.styleable#AidFilter aid-filter}&gt;</code>.

 * <p class="note">Use of this class requires the

 * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present

 * on the device.

 */

public abstract class OffHostApduService extends Service {

    /**

     * The {@link Intent} that must be declared as handled by the service.

     * The {@link Intent} action that must be declared as handled by the service.

     */

    @SdkConstant(SdkConstantType.SERVICE_ACTION)

    public static final String SERVICE_INTERFACE =