From 35bf6288527b177a04100585321a1266f020004a Mon Sep 17 00:00:00 2001 From: Martijn Coenen Date: Mon, 14 Oct 2013 20:39:59 +0200 Subject: [PATCH] NFC card emulation API docs. Bug: 10550319 Change-Id: I3023639d728aa76af89d15e0491b86c7c641648e --- .../nfc/cardemulation/CardEmulation.java | 109 +++++++------- .../nfc/cardemulation/HostApduService.java | 141 +++++++++++++++--- .../nfc/cardemulation/OffHostApduService.java | 129 +++++++++++++--- core/java/android/nfc/tech/NfcBarcode.java | 14 +- 4 files changed, 296 insertions(+), 97 deletions(-) diff --git a/core/java/android/nfc/cardemulation/CardEmulation.java b/core/java/android/nfc/cardemulation/CardEmulation.java index 3cd7863ff4247..58d9616c72c4b 100644 --- a/core/java/android/nfc/cardemulation/CardEmulation.java +++ b/core/java/android/nfc/cardemulation/CardEmulation.java @@ -33,6 +33,18 @@ import android.util.Log; 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 + * NFC card emulation developer guide.

+ * + *

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"; @@ -50,32 +62,28 @@ public final class 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"; @@ -83,49 +91,23 @@ public final class CardEmulation { * Return value for {@link #getSelectionModeForCategory(String)}. * *

In this mode, the user has set a default service for this - * AID category. If a remote reader selects any of the AIDs + * category. + * + *

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

There are still cases where a service that is - * not the default for a category can selected: - *

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

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

Example: - *

- * In this case, the following will happen when service A - * is the default: - * - * */ public static final int SELECTION_MODE_PREFER_DEFAULT = 0; /** * Return value for {@link #getSelectionModeForCategory(String)}. * - *

In this mode, whenever an AID of this category is selected, - * the user is asked which service he wants to use to handle + *

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; @@ -133,13 +115,16 @@ public final class CardEmulation { /** * Return value for {@link #getSelectionModeForCategory(String)}. * - *

In this mode, the user will only be asked to select a service - * if the selected AID has been registered by multiple applications. + *

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 sCardEmus = new HashMap(); + static HashMap sCardEmus = new HashMap(); static INfcCardEmulation sService; final Context mContext; @@ -149,6 +134,12 @@ public final class CardEmulation { 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(); @@ -188,12 +179,19 @@ public final class CardEmulation { * the default service to handle a card emulation category. * *

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

Requires the {@link android.Manifest.permission#NFC} permission. */ public boolean isDefaultServiceForCategory(ComponentName service, String category) { try { @@ -222,7 +220,9 @@ public final class CardEmulation { * * @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 + * + *

Requires the {@link android.Manifest.permission#NFC} permission. */ public boolean isDefaultServiceForAid(ComponentName service, String aid) { try { @@ -244,16 +244,16 @@ public final class CardEmulation { } /** - * Returns the application selection mode for the passed in category. + * Returns the service selection mode for the passed in category. * Valid return values are: *

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

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

{@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)) { @@ -314,6 +314,7 @@ public final class CardEmulation { } } } + /** * @hide */ diff --git a/core/java/android/nfc/cardemulation/HostApduService.java b/core/java/android/nfc/cardemulation/HostApduService.java index e2c3ca6c57352..ad34e61db910c 100644 --- a/core/java/android/nfc/cardemulation/HostApduService.java +++ b/core/java/android/nfc/cardemulation/HostApduService.java @@ -4,6 +4,7 @@ import android.annotation.SdkConstant; 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; @@ -13,30 +14,136 @@ import android.os.RemoteException; import android.util.Log; /** - *

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

HostApduService is a convenience {@link Service} class that can be + * extended to emulate an NFC card inside an Android + * service component. * - *

To tell the platform which ISO7816 application ID (AIDs) - * are implemented by this service, a {@link #SERVICE_META_DATA} + *

+ *

Developer Guide

+ * For a general introduction into the topic of card emulation, + * please read the + * NFC card emulation developer guide.

+ *
+ * + *

NFC Protocols

+ *

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

Service selection

+ *

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

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

AID groups

+ *

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

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

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

AID groups and categories

+ *

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

You can use + * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)} + * to determine if your service is the default handler for a category. + * + *

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

Service AID registration

+ *

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

 <service android:name=".MyHostApduService">
+ * example of a HostApduService manifest declaration is shown below:
+ * 
 <service android:name=".MyHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE">
  *     <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"/>
  * </service>

- * 
For more details refer to {@link #SERVICE_META_DATA},
- * <{@link android.R.styleable#HostApduService host-apdu-service}>,
- * <{@link android.R.styleable#AidGroup aid-group}> and
- * <{@link android.R.styleable#AidFilter aid-filter}>.
- * 
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:
+ * 
+ * <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>
+ * 

+ *
+ * 
The {@link android.R.styleable#HostApduService <host-apdu-service>} 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.
+ * 
The {@link android.R.styleable#HostApduService <host-apdu-service>} 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.
+ * 
AID conflict resolution

+ * 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)}.
+ *
+ * 
Data exchange

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

+ * These two scenarios are indicated by a call to {@link #onDeactivated(int)}.
+ *
+ * 
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 =
@@ -260,7 +367,7 @@ public abstract class HostApduService extends Service {
      * 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.
diff --git a/core/java/android/nfc/cardemulation/OffHostApduService.java b/core/java/android/nfc/cardemulation/OffHostApduService.java
index 15f63f9fed53f..0d01762ae8e26 100644
--- a/core/java/android/nfc/cardemulation/OffHostApduService.java
+++ b/core/java/android/nfc/cardemulation/OffHostApduService.java
@@ -4,41 +4,126 @@ import android.annotation.SdkConstant;
 import android.annotation.SdkConstant.SdkConstantType;
 import android.app.Service;
 import android.content.Intent;
+import android.content.pm.PackageManager;
 import android.os.IBinder;
 
 /**
- * 
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.
+ * 
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.
+ *
+ * 

+ * 
Developer Guide

+ * For a general introduction into the topic of card emulation,
+ * please read the 
+ * NFC card emulation developer guide.

+ * 

+ *
+ * 
NFC Protocols

+ * 
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.
+ *
+ * 
Service selection

+ * 
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.
+ *
+ * 
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.
+ *
+ * 
AID groups

+ * 
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).
+ *
+ * 
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:
+ * 

+ * 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}.
+ * 
AID groups and categories

+ * 
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.
+ *
+ * 
You can use
+ * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)}
+ * to determine if your off-host service is the default handler for a category.
+ *
+ * 
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.
+ *
+ * 
Service AID registration

+ * 
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:
+ * 
 <service android:name=".MyOffHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE">
+ *     <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"/>
+ * </service>

+ *
+ * This meta-data tag points to an apduservice.xml file.
+ * An example of this file with a single AID group declaration is shown below:
+ * 
+ * <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>
+ * 

+ *
+ * 
The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} 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.
+ *
+ * 
The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} 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.
  *
  * 
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.
  *
  * 
The service may define additional actions outside of the
  * Android namespace that provide further interaction with
  * the off-host execution environment.
  *
- * 
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:
- * 
 <service android:name=".MyOffHostApduService">
- *     <intent-filter>
- *         <action android:name="android.nfc.OffHostApduService"/>
- *     </intent-filter>
- *     <meta-data android:name="android.nfc.OffHostApduService" android:resource="@xml/apduservice.xml"/>
- * </service>

- * 
For more details refer to {@link #SERVICE_META_DATA},
- * <{@link android.R.styleable#OffHostApduService offhost-apdu-service}>,
- * <{@link android.R.styleable#AidGroup aid-group}> and
- * <{@link android.R.styleable#AidFilter aid-filter}>.
+ * 
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 =
diff --git a/core/java/android/nfc/tech/NfcBarcode.java b/core/java/android/nfc/tech/NfcBarcode.java
index 76627deb4e108..8901f287c47a2 100644
--- a/core/java/android/nfc/tech/NfcBarcode.java
+++ b/core/java/android/nfc/tech/NfcBarcode.java
@@ -102,15 +102,21 @@ public final class NfcBarcode extends BasicTagTechnology {
      *       
      *     
The following 12 bytes are payload:

+     *            following the limitations defined in RFC3987.
+     *            {@see RFC 3987}
+     *       
  •  In case of GS1 EPC data, see 
+     *            GS1 Electronic Product Code (EPC) Tag Data Standard (TDS) for more details.
+     *       
    • 
+     *     
      *     
    The last 2 bytes comprise the CRC.
      *     
      * 
    Does not cause any RF activity and does not block.
      *
      * @return a byte array containing the barcode
+     * @see 
+     *      Kovio 128-bit NFC barcode datasheet
+     * @see 
+     *      Kovio 128-bit NFC barcode data format
      */
     public byte[] getBarcode() {
         switch (mType) {