HostApduService
public abstract class HostApduService
extends Service
java.lang.Object | ||||
โณ | android.content.Context | |||
โณ | android.content.ContextWrapper | |||
โณ | android.app.Service | |||
โณ | android.nfc.cardemulation.HostApduService |
HostApduService is a convenience Service
class that can be extended to emulate an NFC card inside an Android service component.
Developer Guide
For a general introduction to card emulation, see Host-based Card Emulation.NFC Protocols
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.
Service selection
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.
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.
AID groups
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).
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:
- All AIDs in the group are routed to this service
- No AIDs in the group are routed to this service
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.
AID groups and categories
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 isDefaultServiceForCategory(android.content.ComponentName, String)
to determine if your service is the default handler for a category.
In this version of the platform, the only known categories are CATEGORY_PAYMENT
and 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 CATEGORY_OTHER
category.
Service AID registration
To tell the platform which AIDs groups are requested by this service, a SERVICE_META_DATA
entry must be included in the declaration of the service. An example of a HostApduService manifest declaration is shown below:
<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>
This meta-data tag points to an apduservice.xml file. An example of this file with a single AID group declaration is shown below:
<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>
The <host-apdu-service>
is required to contain a <android:description>
attribute that contains a user-friendly description of the service that may be shown in UI. The <requireDeviceUnlock>
attribute can be used to specify that the device must be unlocked before this service can be invoked to handle APDUs.
The <host-apdu-service>
must contain one or more <aid-group>
tags. Each <aid-group>
must contain one or more <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.
AID conflict resolution
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 getSelectionModeForCategory(String)
.
Data exchange
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 processCommandApdu(byte[], Bundle)
, until either:
- The NFC link is broken
- A "SELECT AID" APDU is received which resolves to another service
These two scenarios are indicated by a call to onDeactivated(int)
.
Use of this class requires the FEATURE_NFC_HOST_CARD_EMULATION
to be present on the device.
Summary
Constants | |
---|---|
int | DEACTIVATION_DESELECTED Reason for |
int | DEACTIVATION_LINK_LOSS Reason for |
String | SERVICE_INTERFACE The |
String | SERVICE_META_DATA The name of the meta-data element that contains more information about this service. |
Inherited constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class android.app.Service
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class android.content.Context
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface android.content.ComponentCallbacks2
|
Public constructors | |
---|---|
HostApduService() |
Public methods | |
---|---|
final void | notifyUnhandled() 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. |
final IBinder | onBind(Intent intent) Return the communication channel to the service. |
abstract void | onDeactivated(int reason) This method will be called in two possible scenarios: |
abstract byte[] | processCommandApdu(byte[] commandApdu, Bundle extras) This method will be called when a command APDU has been received from a remote device. |
final void | sendResponseApdu(byte[] responseApdu) Sends a response APDU back to the remote device. |
Inherited methods | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class android.app.Service
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class android.content.ContextWrapper
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class android.content.Context
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class java.lang.Object
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface android.content.ComponentCallbacks2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface android.content.ComponentCallbacks
|
Constants
DEACTIVATION_DESELECTED
int DEACTIVATION_DESELECTED
Reason for onDeactivated(int)
.
Indicates deactivation was due to a different AID being selected (which implicitly deselects the AID currently active on the logical channel).
Note that this next AID may still be resolved to this service, in which case processCommandApdu(byte[], Bundle)
will be called again.
Constant Value: 1 (0x00000001)
DEACTIVATION_LINK_LOSS
int DEACTIVATION_LINK_LOSS
Reason for onDeactivated(int)
. Indicates deactivation was due to the NFC link being lost.
Constant Value: 0 (0x00000000)
SERVICE_INTERFACE
String SERVICE_INTERFACE
The Intent
action that must be declared as handled by the service.
Constant Value: "android.nfc.cardemulation.action.HOST_APDU_SERVICE"
SERVICE_META_DATA
String SERVICE_META_DATA
The name of the meta-data element that contains more information about this service.
Constant Value: "android.nfc.cardemulation.host_apdu_service"
Public constructors
Public methods
notifyUnhandled
void notifyUnhandled ()
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.
Note: this method may be called anywhere between the first processCommandApdu(byte[], Bundle)
call and a onDeactivated(int)
call.
onBind
IBinder onBind (Intent intent)
Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder
is usually for a complex interface that has been described using aidl.
Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.
Parameters | |
---|---|
intent | Intent : The Intent that was used to bind to this service, as given to Context.bindService . Note that any extras that were included with the Intent at that point will not be seen here. |
Returns | |
---|---|
IBinder | Return an IBinder through which clients can call on to the service. |
onDeactivated
void onDeactivated (int reason)
This method will be called in two possible scenarios:
Parameters | |
---|---|
reason | int : Either DEACTIVATION_LINK_LOSS or DEACTIVATION_DESELECTED |
processCommandApdu
byte[] processCommandApdu (byte[] commandApdu, Bundle extras)
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.
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.
This method is running on the main thread of your application. If you cannot return a response APDU immediately, return null and use the sendResponseApdu(byte[])
method later.
Parameters | |
---|---|
commandApdu | byte : The APDU that was received from the remote device |
extras | Bundle : A bundle containing extra data. May be null. |
Returns | |
---|---|
byte[] | a byte-array containing the response APDU, or null if no response APDU can be sent at this point. |
sendResponseApdu
void sendResponseApdu (byte[] responseApdu)
Sends a response APDU back to the remote device.
Note: this method may be called from any thread and will not block.
Parameters | |
---|---|
responseApdu | byte : A byte-array containing the reponse APDU. |