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. * *
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. * *
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. * *
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: *
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. * *
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 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. * *
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} action that must be declared as handled by the service. */ @SdkConstant(SdkConstantType.SERVICE_ACTION) public static final String SERVICE_INTERFACE = "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"; /** * The name of the meta-data element that contains * more information about this service. */ public static final String SERVICE_META_DATA = "android.nfc.cardemulation.off_host_apdu_service"; /** * The Android platform itself will not bind to this service, * but merely uses its declaration to keep track of what AIDs * the service is interested in. This information is then used * to present the user with a list of applications that can handle * an AID, as well as correctly route those AIDs either to the host (in case * the user preferred a {@link HostApduService}), or to an off-host * execution environment (in case the user preferred a {@link OffHostApduService}. * * Implementers may define additional actions outside of the * Android namespace that allow further interactions with * the off-host execution environment. Such implementations * would need to override this method. */ public abstract IBinder onBind(Intent intent); }