Java tutorial
/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.nfc.cardemulation; 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; import android.os.Message; import android.os.Messenger; import android.os.RemoteException; import android.util.Log; /** * <p>HostApduService is a convenience {@link Service} class that can be * extended to emulate an NFC card inside an Android * service component. * * <div class="special reference"> * <h3>Developer Guide</h3> * For a general introduction to card emulation, see * <a href="{@docRoot}guide/topics/connectivity/nfc/hce.html"> * Host-based Card Emulation</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 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.cardemulation.action.HOST_APDU_SERVICE"/> * </intent-filter> * <meta-data android:name="android.nfc.cardemulation.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> * <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} action that must be declared as handled by the service. */ @SdkConstant(SdkConstantType.SERVICE_ACTION) public static final String SERVICE_INTERFACE = "android.nfc.cardemulation.action.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.host_apdu_service"; /** * Reason for {@link #onDeactivated(int)}. * Indicates deactivation was due to the NFC link * being lost. */ public static final int DEACTIVATION_LINK_LOSS = 0; /** * Reason for {@link #onDeactivated(int)}. * * <p>Indicates deactivation was due to a different AID * being selected (which implicitly deselects the AID * currently active on the logical channel). * * <p>Note that this next AID may still be resolved to this * service, in which case {@link #processCommandApdu(byte[], Bundle)} * will be called again. */ public static final int DEACTIVATION_DESELECTED = 1; static final String TAG = "ApduService"; /** * MSG_COMMAND_APDU is sent by NfcService when * a 7816-4 command APDU has been received. * * @hide */ public static final int MSG_COMMAND_APDU = 0; /** * MSG_RESPONSE_APDU is sent to NfcService to send * a response APDU back to the remote device. * * @hide */ public static final int MSG_RESPONSE_APDU = 1; /** * MSG_DEACTIVATED is sent by NfcService when * the current session is finished; either because * another AID was selected that resolved to * another service, or because the NFC link * was deactivated. * * @hide */ public static final int MSG_DEACTIVATED = 2; /** * * @hide */ public static final int MSG_UNHANDLED = 3; /** * @hide */ public static final String KEY_DATA = "data"; /** * Messenger interface to NfcService for sending responses. * Only accessed on main thread by the message handler. * * @hide */ Messenger mNfcService = null; final Messenger mMessenger = new Messenger(new MsgHandler()); final class MsgHandler extends Handler { @Override public void handleMessage(Message msg) { switch (msg.what) { case MSG_COMMAND_APDU: Bundle dataBundle = msg.getData(); if (dataBundle == null) { return; } if (mNfcService == null) mNfcService = msg.replyTo; byte[] apdu = dataBundle.getByteArray(KEY_DATA); if (apdu != null) { byte[] responseApdu = processCommandApdu(apdu, null); if (responseApdu != null) { if (mNfcService == null) { Log.e(TAG, "Response not sent; service was deactivated."); return; } Message responseMsg = Message.obtain(null, MSG_RESPONSE_APDU); Bundle responseBundle = new Bundle(); responseBundle.putByteArray(KEY_DATA, responseApdu); responseMsg.setData(responseBundle); responseMsg.replyTo = mMessenger; try { mNfcService.send(responseMsg); } catch (RemoteException e) { Log.e("TAG", "Response not sent; RemoteException calling into " + "NfcService."); } } } else { Log.e(TAG, "Received MSG_COMMAND_APDU without data."); } break; case MSG_RESPONSE_APDU: if (mNfcService == null) { Log.e(TAG, "Response not sent; service was deactivated."); return; } try { msg.replyTo = mMessenger; mNfcService.send(msg); } catch (RemoteException e) { Log.e(TAG, "RemoteException calling into NfcService."); } break; case MSG_DEACTIVATED: // Make sure we won't call into NfcService again mNfcService = null; onDeactivated(msg.arg1); break; case MSG_UNHANDLED: if (mNfcService == null) { Log.e(TAG, "notifyUnhandled not sent; service was deactivated."); return; } try { msg.replyTo = mMessenger; mNfcService.send(msg); } catch (RemoteException e) { Log.e(TAG, "RemoteException calling into NfcService."); } break; default: super.handleMessage(msg); } } } @Override public final IBinder onBind(Intent intent) { return mMessenger.getBinder(); } /** * Sends a response APDU back to the remote device. * * <p>Note: this method may be called from any thread and will not block. * @param responseApdu A byte-array containing the reponse APDU. */ public final void sendResponseApdu(byte[] responseApdu) { Message responseMsg = Message.obtain(null, MSG_RESPONSE_APDU); Bundle dataBundle = new Bundle(); dataBundle.putByteArray(KEY_DATA, responseApdu); responseMsg.setData(dataBundle); try { mMessenger.send(responseMsg); } catch (RemoteException e) { Log.e("TAG", "Local messenger has died."); } } /** * Calling this method allows the service to tell the OS * that it won't be able to complete this transaction - * for example, because it requires data connectivity * that is not present at that moment. * * The OS may use this indication to give the user a list * of alternative applications that can handle the last * AID that was selected. If the user would select an * application from the list, that action by itself * will not cause the default to be changed; the selected * application will be invoked for the next tap only. * * If there are no other applications that can handle * this transaction, the OS will show an error dialog * indicating your service could not complete the * transaction. * * <p>Note: this method may be called anywhere between * the first {@link #processCommandApdu(byte[], Bundle)} * call and a {@link #onDeactivated(int)} call. */ public final void notifyUnhandled() { Message unhandledMsg = Message.obtain(null, MSG_UNHANDLED); try { mMessenger.send(unhandledMsg); } catch (RemoteException e) { Log.e("TAG", "Local messenger has died."); } } /** * <p>This method will be called when a command APDU has been received * from a remote device. A response APDU can be provided directly * by returning a byte-array in this method. Note that in general * response APDUs must be sent as quickly as possible, given the fact * that the user is likely holding his device over an NFC reader * when this method is called. * * <p class="note">If there are multiple services that have registered for the same * AIDs in their meta-data entry, you will only get called if the user has * explicitly selected your service, either as a default or just for the next tap. * * <p class="note">This method is running on the main thread of your application. * If you cannot return a response APDU immediately, return null * and use the {@link #sendResponseApdu(byte[])} method later. * * @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. */ public abstract byte[] processCommandApdu(byte[] commandApdu, Bundle extras); /** * This method will be called in two possible scenarios: * <li>The NFC link has been deactivated or lost * <li>A different AID has been selected and was resolved to a different * service component * @param reason Either {@link #DEACTIVATION_LINK_LOSS} or {@link #DEACTIVATION_DESELECTED} */ public abstract void onDeactivated(int reason); }