1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.nfc.cardemulation; 18 19 import android.annotation.Nullable; 20 import android.annotation.SdkConstant; 21 import android.annotation.SdkConstant.SdkConstantType; 22 import android.app.Service; 23 import android.compat.annotation.UnsupportedAppUsage; 24 import android.content.ComponentName; 25 import android.content.Intent; 26 import android.os.Bundle; 27 import android.os.Handler; 28 import android.os.IBinder; 29 import android.os.Message; 30 import android.os.Messenger; 31 import android.os.RemoteException; 32 import android.util.Log; 33 34 /** 35 * <p>HostNfcFService is a convenience {@link Service} class that can be 36 * extended to emulate an NFC-F card inside an Android service component. 37 * 38 * <h3>NFC Protocols</h3> 39 * <p>Cards emulated by this class are based on the NFC-Forum NFC-F 40 * protocol (based on the JIS-X 6319-4 specification.)</p> 41 * 42 * <h3>System Code and NFCID2 registration</h3> 43 * <p>A {@link HostNfcFService HostNfcFService service} can register 44 * exactly one System Code and one NFCID2. For details about the use of 45 * System Code and NFCID2, see the NFC Forum Digital specification.</p> 46 * <p>To statically register a System Code and NFCID2 with the service, a {@link #SERVICE_META_DATA} 47 * entry must be included in the declaration of the service. 48 * 49 * <p>All {@link HostNfcFService HostNfcFService} declarations in the manifest must require the 50 * {@link android.Manifest.permission#BIND_NFC_SERVICE} permission 51 * in their <service> tag, to ensure that only the platform can bind to your service.</p> 52 * 53 * <p>An example of a HostNfcFService manifest declaration is shown below: 54 * 55 * <pre> <service android:name=".MyHostNfcFService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE"> 56 * <intent-filter> 57 * <action android:name="android.nfc.cardemulation.action.HOST_NFCF_SERVICE"/> 58 * </intent-filter> 59 * <meta-data android:name="android.nfc.cardemulation.host_nfcf_service" android:resource="@xml/nfcfservice"/> 60 * </service></pre> 61 * 62 * This meta-data tag points to an nfcfservice.xml file. 63 * An example of this file with a System Code and NFCID2 declaration is shown below: 64 * <pre> 65 * <host-nfcf-service xmlns:android="http://schemas.android.com/apk/res/android" 66 * android:description="@string/servicedesc"> 67 * <system-code-filter android:name="4000"/> 68 * <nfcid2-filter android:name="02FE000000000000"/> 69 <t3tPmm-filter android:name="FFFFFFFFFFFFFFFF"/> 70 * </host-nfcf-service> 71 * </pre> 72 * 73 * <p>The {@link android.R.styleable#HostNfcFService <host-nfcf-service>} is required 74 * to contain a 75 * {@link android.R.styleable#HostApduService_description <android:description>} 76 * attribute that contains a user-friendly description of the service that may be shown in UI. 77 * <p>The {@link android.R.styleable#HostNfcFService <host-nfcf-service>} must 78 * contain: 79 * <ul> 80 * <li>Exactly one {@link android.R.styleable#SystemCodeFilter <system-code-filter>} tag.</li> 81 * <li>Exactly one {@link android.R.styleable#Nfcid2Filter <nfcid2-filter>} tag.</li> 82 * <li>Zero or one {@link android.R.styleable#T3tPmmFilter <t3tPmm-filter>} tag.</li> 83 * </ul> 84 * </p> 85 * 86 * <p>Alternatively, the System Code and NFCID2 can be dynamically registererd for a service 87 * by using the {@link NfcFCardEmulation#registerSystemCodeForService(ComponentName, String)} and 88 * {@link NfcFCardEmulation#setNfcid2ForService(ComponentName, String)} methods. 89 * </p> 90 * 91 * <h3>Service selection</h3> 92 * <p>When a remote NFC devices wants to communicate with your service, it 93 * sends a SENSF_REQ command to the NFC controller, requesting a System Code. 94 * If a {@link NfcFCardEmulation NfcFCardEmulation service} has registered 95 * this system code and has been enabled by the foreground application, the 96 * NFC controller will respond with the NFCID2 that is registered for this service. 97 * The reader can then continue data exchange with this service by using the NFCID2.</p> 98 * 99 * <h3>Data exchange</h3> 100 * <p>After service selection, all frames addressed to the NFCID2 of this service will 101 * be sent through {@link #processNfcFPacket(byte[], Bundle)}, until the NFC link is 102 * broken.<p> 103 * 104 * <p>When the NFC link is broken, {@link #onDeactivated(int)} will be called.</p> 105 */ 106 public abstract class HostNfcFService extends Service { 107 /** 108 * The {@link Intent} action that must be declared as handled by the service. 109 */ 110 @SdkConstant(SdkConstantType.SERVICE_ACTION) 111 public static final String SERVICE_INTERFACE = 112 "android.nfc.cardemulation.action.HOST_NFCF_SERVICE"; 113 114 /** 115 * The name of the meta-data element that contains 116 * more information about this service. 117 */ 118 public static final String SERVICE_META_DATA = 119 "android.nfc.cardemulation.host_nfcf_service"; 120 121 /** 122 * Reason for {@link #onDeactivated(int)}. 123 * Indicates deactivation was due to the NFC link 124 * being lost. 125 */ 126 public static final int DEACTIVATION_LINK_LOSS = 0; 127 128 static final String TAG = "NfcFService"; 129 130 /** 131 * MSG_COMMAND_PACKET is sent by NfcService when 132 * a NFC-F command packet has been received. 133 * 134 * @hide 135 */ 136 public static final int MSG_COMMAND_PACKET = 0; 137 138 /** 139 * MSG_RESPONSE_PACKET is sent to NfcService to send 140 * a response packet back to the remote device. 141 * 142 * @hide 143 */ 144 public static final int MSG_RESPONSE_PACKET = 1; 145 146 /** 147 * MSG_DEACTIVATED is sent by NfcService when 148 * the current session is finished; because 149 * the NFC link was deactivated. 150 * 151 * @hide 152 */ 153 public static final int MSG_DEACTIVATED = 2; 154 155 /** 156 * @hide 157 */ 158 public static final String KEY_DATA = "data"; 159 160 /** 161 * @hide 162 */ 163 public static final String KEY_MESSENGER = "messenger"; 164 165 /** 166 * @hide 167 */ 168 @UnsupportedAppUsage getNfcService()169 public Messenger getNfcService() { 170 return mNfcService; 171 } 172 173 /** 174 * @hide 175 */ 176 @UnsupportedAppUsage getMessenger()177 public Messenger getMessenger() { 178 return mMessenger; 179 } 180 /** 181 * @hide 182 */ 183 @UnsupportedAppUsage setNfcService(Messenger nfcService)184 public void setNfcService(Messenger nfcService) { 185 mNfcService = nfcService; 186 } 187 188 /** 189 * Messenger interface to NfcService for sending responses. 190 * Only accessed on main thread by the message handler. 191 * 192 * @hide 193 */ 194 Messenger mNfcService = null; 195 196 final Messenger mMessenger = new Messenger(new HostNfcFServiceMsgHandler(this)); 197 198 @Override onBind(Intent intent)199 public final IBinder onBind(Intent intent) { 200 return mMessenger.getBinder(); 201 } 202 203 /** 204 * Sends a response packet back to the remote device. 205 * 206 * <p>Note: this method may be called from any thread and will not block. 207 * @param responsePacket A byte-array containing the response packet. 208 */ sendResponsePacket(byte[] responsePacket)209 public final void sendResponsePacket(byte[] responsePacket) { 210 Message responseMsg = Message.obtain(null, MSG_RESPONSE_PACKET); 211 Bundle dataBundle = new Bundle(); 212 dataBundle.putByteArray(KEY_DATA, responsePacket); 213 responseMsg.setData(dataBundle); 214 try { 215 mMessenger.send(responseMsg); 216 } catch (RemoteException e) { 217 Log.e("TAG", "Local messenger has died."); 218 } 219 } 220 221 /** 222 * <p>This method will be called when a NFC-F packet has been received 223 * from a remote device. A response packet can be provided directly 224 * by returning a byte-array in this method. Note that in general 225 * response packets must be sent as quickly as possible, given the fact 226 * that the user is likely holding their device over an NFC reader 227 * when this method is called. 228 * 229 * <p class="note">This method is running on the main thread of your application. 230 * If you cannot return a response packet immediately, return null 231 * and use the {@link #sendResponsePacket(byte[])} method later. 232 * 233 * @param commandPacket The NFC-F packet that was received from the remote device 234 * @param extras A bundle containing extra data. May be null. 235 * @return a byte-array containing the response packet, or null if no 236 * response packet can be sent at this point. 237 */ processNfcFPacket(byte[] commandPacket, Bundle extras)238 public abstract byte[] processNfcFPacket(byte[] commandPacket, Bundle extras); 239 240 /** 241 * This method will be called in following possible scenarios: 242 * <li>The NFC link has been lost 243 * @param reason {@link #DEACTIVATION_LINK_LOSS} 244 */ onDeactivated(int reason)245 public abstract void onDeactivated(int reason); 246 } 247