Loading core/java/android/nfc/cardemulation/CardEmulation.java +55 −54 Original line number Diff line number Diff line Loading @@ -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 <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"; Loading @@ -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"; Loading @@ -83,49 +91,23 @@ public final class CardEmulation { * 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; Loading @@ -133,13 +115,16 @@ public final class CardEmulation { /** * 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; Loading @@ -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(); Loading Loading @@ -188,12 +179,19 @@ public final class CardEmulation { * 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 { Loading Loading @@ -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 * * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. */ public boolean isDefaultServiceForAid(ComponentName service, String aid) { try { Loading @@ -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: * <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)) { Loading Loading @@ -314,6 +314,7 @@ public final class CardEmulation { } } } /** * @hide */ Loading core/java/android/nfc/cardemulation/HostApduService.java +124 −17 Original line number Diff line number Diff line Loading @@ -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; Loading @@ -13,30 +14,136 @@ import android.os.RemoteException; 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> <service android:name=".MyHostApduService"> * example of a HostApduService manifest declaration is shown below: * <pre> <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></pre> * <p>For more details refer to {@link #SERVICE_META_DATA}, * <code><{@link android.R.styleable#HostApduService host-apdu-service}></code>, * <code><{@link android.R.styleable#AidGroup aid-group}></code> and * <code><{@link android.R.styleable#AidFilter aid-filter}></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 <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. * <p>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. * <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 = Loading Loading @@ -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. Loading core/java/android/nfc/cardemulation/OffHostApduService.java +107 −22 Original line number Diff line number Diff line Loading @@ -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; /** * <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> <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></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 <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. * * <p>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. * * <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> <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></pre> * <p>For more details refer to {@link #SERVICE_META_DATA}, * <code><{@link android.R.styleable#OffHostApduService offhost-apdu-service}></code>, * <code><{@link android.R.styleable#AidGroup aid-group}></code> and * <code><{@link android.R.styleable#AidFilter aid-filter}></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 = Loading core/java/android/nfc/tech/NfcBarcode.java +10 −4 File changed.Preview size limit exceeded, changes collapsed. Show changes Loading
core/java/android/nfc/cardemulation/CardEmulation.java +55 −54 Original line number Diff line number Diff line Loading @@ -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 <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"; Loading @@ -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"; Loading @@ -83,49 +91,23 @@ public final class CardEmulation { * 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; Loading @@ -133,13 +115,16 @@ public final class CardEmulation { /** * 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; Loading @@ -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(); Loading Loading @@ -188,12 +179,19 @@ public final class CardEmulation { * 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 { Loading Loading @@ -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 * * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. */ public boolean isDefaultServiceForAid(ComponentName service, String aid) { try { Loading @@ -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: * <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)) { Loading Loading @@ -314,6 +314,7 @@ public final class CardEmulation { } } } /** * @hide */ Loading
core/java/android/nfc/cardemulation/HostApduService.java +124 −17 Original line number Diff line number Diff line Loading @@ -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; Loading @@ -13,30 +14,136 @@ import android.os.RemoteException; 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> <service android:name=".MyHostApduService"> * example of a HostApduService manifest declaration is shown below: * <pre> <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></pre> * <p>For more details refer to {@link #SERVICE_META_DATA}, * <code><{@link android.R.styleable#HostApduService host-apdu-service}></code>, * <code><{@link android.R.styleable#AidGroup aid-group}></code> and * <code><{@link android.R.styleable#AidFilter aid-filter}></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 <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. * <p>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. * <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 = Loading Loading @@ -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. Loading
core/java/android/nfc/cardemulation/OffHostApduService.java +107 −22 Original line number Diff line number Diff line Loading @@ -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; /** * <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> <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></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 <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. * * <p>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. * * <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> <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></pre> * <p>For more details refer to {@link #SERVICE_META_DATA}, * <code><{@link android.R.styleable#OffHostApduService offhost-apdu-service}></code>, * <code><{@link android.R.styleable#AidGroup aid-group}></code> and * <code><{@link android.R.styleable#AidFilter aid-filter}></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 = Loading
core/java/android/nfc/tech/NfcBarcode.java +10 −4 File changed.Preview size limit exceeded, changes collapsed. Show changes
