1 package android.nfc.cardemulation; 2 3 import android.annotation.SdkConstant; 4 import android.annotation.SdkConstant.SdkConstantType; 5 import android.app.Service; 6 import android.content.Intent; 7 import android.content.pm.PackageManager; 8 import android.os.IBinder; 9 10 /** 11 * <p>OffHostApduService is a convenience {@link Service} class that can be 12 * extended to describe one or more NFC applications that are residing 13 * off-host, for example on an embedded secure element or a UICC. 14 * 15 * <div class="special reference"> 16 * <h3>Developer Guide</h3> 17 * For a general introduction into the topic of card emulation, 18 * please read the <a href="{@docRoot}guide/topics/nfc/ce.html"> 19 * NFC card emulation developer guide.</a></p> 20 * </div> 21 * 22 * <h3>NFC Protocols</h3> 23 * <p>Off-host applications represented by this class are based on the NFC-Forum ISO-DEP 24 * protocol (based on ISO/IEC 14443-4) and support processing 25 * command Application Protocol Data Units (APDUs) as 26 * defined in the ISO/IEC 7816-4 specification. 27 * 28 * <h3>Service selection</h3> 29 * <p>When a remote NFC device wants to talk to your 30 * off-host NFC application, it sends a so-called 31 * "SELECT AID" APDU as defined in the ISO/IEC 7816-4 specification. 32 * The AID is an application identifier defined in ISO/IEC 7816-4. 33 * 34 * <p>The registration procedure for AIDs is defined in the 35 * ISO/IEC 7816-5 specification. If you don't want to register an 36 * AID, you are free to use AIDs in the proprietary range: 37 * bits 8-5 of the first byte must each be set to '1'. For example, 38 * "0xF00102030405" is a proprietary AID. If you do use proprietary 39 * AIDs, it is recommended to choose an AID of at least 6 bytes, 40 * to reduce the risk of collisions with other applications that 41 * might be using proprietary AIDs as well. 42 * 43 * <h3>AID groups</h3> 44 * <p>In some cases, an off-host environment may need to register multiple AIDs 45 * to implement a certain application, and it needs to be sure 46 * that it is the default handler for all of these AIDs (as opposed 47 * to some AIDs in the group going to another service). 48 * 49 * <p>An AID group is a list of AIDs that should be considered as 50 * belonging together by the OS. For all AIDs in an AID group, the 51 * OS will guarantee one of the following: 52 * <ul> 53 * <li>All AIDs in the group are routed to the off-host execution environment 54 * <li>No AIDs in the group are routed to the off-host execution environment 55 * </ul> 56 * In other words, there is no in-between state, where some AIDs 57 * in the group can be routed to this off-host execution environment, 58 * and some to another or a host-based {@link HostApduService}. 59 * <h3>AID groups and categories</h3> 60 * <p>Each AID group can be associated with a category. This allows 61 * the Android OS to classify services, and it allows the user to 62 * set defaults at the category level instead of the AID level. 63 * 64 * <p>You can use 65 * {@link CardEmulation#isDefaultServiceForCategory(android.content.ComponentName, String)} 66 * to determine if your off-host service is the default handler for a category. 67 * 68 * <p>In this version of the platform, the only known categories 69 * are {@link CardEmulation#CATEGORY_PAYMENT} and {@link CardEmulation#CATEGORY_OTHER}. 70 * AID groups without a category, or with a category that is not recognized 71 * by the current platform version, will automatically be 72 * grouped into the {@link CardEmulation#CATEGORY_OTHER} category. 73 * 74 * <h3>Service AID registration</h3> 75 * <p>To tell the platform which AIDs 76 * reside off-host and are managed by this service, a {@link #SERVICE_META_DATA} 77 * entry must be included in the declaration of the service. An 78 * example of a OffHostApduService manifest declaration is shown below: 79 * <pre> <service android:name=".MyOffHostApduService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"> 80 * <intent-filter> 81 * <action android:name="android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"/> 82 * </intent-filter> 83 * <meta-data android:name="android.nfc.cardemulation.off_host_apdu_ervice" android:resource="@xml/apduservice"/> 84 * </service></pre> 85 * 86 * This meta-data tag points to an apduservice.xml file. 87 * An example of this file with a single AID group declaration is shown below: 88 * <pre> 89 * <offhost-apdu-service xmlns:android="http://schemas.android.com/apk/res/android" 90 * android:description="@string/servicedesc"> 91 * <aid-group android:description="@string/subscription" android:category="other"> 92 * <aid-filter android:name="F0010203040506"/> 93 * <aid-filter android:name="F0394148148100"/> 94 * </aid-group> 95 * </offhost-apdu-service> 96 * </pre> 97 * 98 * <p>The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} is required 99 * to contain a 100 * {@link android.R.styleable#OffHostApduService_description <android:description>} 101 * attribute that contains a user-friendly description of the service that may be shown in UI. 102 * 103 * <p>The {@link android.R.styleable#OffHostApduService <offhost-apdu-service>} must 104 * contain one or more {@link android.R.styleable#AidGroup <aid-group>} tags. 105 * Each {@link android.R.styleable#AidGroup <aid-group>} must contain one or 106 * more {@link android.R.styleable#AidFilter <aid-filter>} tags, each of which 107 * contains a single AID. The AID must be specified in hexadecimal format, and contain 108 * an even number of characters. 109 * 110 * <p>This registration will allow the service to be included 111 * as an option for being the default handler for categories. 112 * The Android OS will take care of correctly 113 * routing the AIDs to the off-host execution environment, 114 * based on which service the user has selected to be the handler for a certain category. 115 * 116 * <p>The service may define additional actions outside of the 117 * Android namespace that provide further interaction with 118 * the off-host execution environment. 119 * 120 * <p class="note">Use of this class requires the 121 * {@link PackageManager#FEATURE_NFC_HOST_CARD_EMULATION} to be present 122 * on the device. 123 */ 124 public abstract class OffHostApduService extends Service { 125 /** 126 * The {@link Intent} action that must be declared as handled by the service. 127 */ 128 @SdkConstant(SdkConstantType.SERVICE_ACTION) 129 public static final String SERVICE_INTERFACE = 130 "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"; 131 132 /** 133 * The name of the meta-data element that contains 134 * more information about this service. 135 */ 136 public static final String SERVICE_META_DATA = 137 "android.nfc.cardemulation.off_host_apdu_service"; 138 139 /** 140 * The Android platform itself will not bind to this service, 141 * but merely uses its declaration to keep track of what AIDs 142 * the service is interested in. This information is then used 143 * to present the user with a list of applications that can handle 144 * an AID, as well as correctly route those AIDs either to the host (in case 145 * the user preferred a {@link HostApduService}), or to an off-host 146 * execution environment (in case the user preferred a {@link OffHostApduService}. 147 * 148 * Implementers may define additional actions outside of the 149 * Android namespace that allow further interactions with 150 * the off-host execution environment. Such implementations 151 * would need to override this method. 152 */ onBind(Intent intent)153 public abstract IBinder onBind(Intent intent); 154 } 155