Classes

public abstract class

OffHostApduService

extends Service

java.lang.Object
↳	android.content.Context
	↳	android.content.ContextWrapper
		↳	android.app.Service
			↳	android.nfc.cardemulation.OffHostApduService

Class Overview

OffHostApduService is a convenience 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.

Developer Guide

For a general introduction into the topic of card emulation, please read the NFC card emulation developer guide.

NFC Protocols

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.

Service selection

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.

AID groups

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:

All AIDs in the group are routed to the off-host execution environment
No AIDs in the group are routed to the off-host execution environment

In other words, there is no in-between state, where some AIDs in the group can be routed to this off-host execution environment, and some to another or a host-based


       
        HostApduService

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 off-host 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 reside off-host and are managed by this service, a 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 <offhost-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 <offhost-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.

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 FEATURE_NFC_HOST_CARD_EMULATION to be present on the device.

Summary

Constants
String	SERVICE_INTERFACE	The `Intent` action that must be declared as handled by the service.
String	SERVICE_META_DATA	The name of the meta-data element that contains more information about this service.

[Expand]

Inherited Constants

From class android.app.Service

From class android.content.Context

From interface android.content.ComponentCallbacks2

int	TRIM_MEMORY_BACKGROUND	Level for `onTrimMemory(int)` : the process has gone on to the LRU list.
int	TRIM_MEMORY_COMPLETE	Level for `onTrimMemory(int)` : the process is nearing the end of the background LRU list, and if more memory isn't found soon it will be killed.
int	TRIM_MEMORY_MODERATE	Level for `onTrimMemory(int)` : the process is around the middle of the background LRU list; freeing memory can help the system keep other processes running later in the list for better overall performance.
int	TRIM_MEMORY_RUNNING_CRITICAL	Level for `onTrimMemory(int)` : the process is not an expendable background process, but the device is running extremely low on memory and is about to not be able to keep any background processes running.
int	TRIM_MEMORY_RUNNING_LOW	Level for `onTrimMemory(int)` : the process is not an expendable background process, but the device is running low on memory.
int	TRIM_MEMORY_RUNNING_MODERATE	Level for `onTrimMemory(int)` : the process is not an expendable background process, but the device is running moderately low on memory.
int	TRIM_MEMORY_UI_HIDDEN	Level for `onTrimMemory(int)` : the process had been showing a user interface, and is no longer doing so.

Public Constructors
	OffHostApduService ()

Public Methods
abstract IBinder	onBind ( Intent intent) 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.

[Expand]

Inherited Methods

From class android.app.Service

void	dump ( FileDescriptor fd, PrintWriter writer, String[] args) Print the Service's state into the given stream.
final Application	getApplication () Return the application that owns this service.
abstract IBinder	onBind ( Intent intent) Return the communication channel to the service.
void	onConfigurationChanged ( Configuration newConfig) Called by the system when the device configuration changes while your component is running.
void	onCreate () Called by the system when the service is first created.
void	onDestroy () Called by the system to notify a Service that it is no longer used and is being removed.
void	onLowMemory () This is called when the overall system is running low on memory, and actively running processes should trim their memory usage.
void	onRebind ( Intent intent) Called when new clients have connected to the service, after it had previously been notified that all had disconnected in its `onUnbind(Intent)` .
void	onStart ( Intent intent, int startId) This method was deprecated in API level 5. Implement `onStartCommand(Intent, int, int)` instead.
int	onStartCommand ( Intent intent, int flags, int startId) Called by the system every time a client explicitly starts the service by calling `startService(Intent)` , providing the arguments it supplied and a unique integer token representing the start request.
void	onTaskRemoved ( Intent rootIntent) This is called if the service is currently running and the user has removed a task that comes from the service's application.
void	onTrimMemory (int level) Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process.
boolean	onUnbind ( Intent intent) Called when all clients have disconnected from a particular interface published by the service.
final void	startForeground (int id, Notification notification) Make this service run in the foreground, supplying the ongoing notification to be shown to the user while in this state.
final void	stopForeground (boolean removeNotification) Remove this service from foreground state, allowing it to be killed if more memory is needed.
final void	stopSelf () Stop the service, if it was previously started.
final void	stopSelf (int startId) Old version of `stopSelfResult(int)` that doesn't return a result.
final boolean	stopSelfResult (int startId) Stop the service if the most recent time it was started was `startId` .

From class android.content.ContextWrapper

From class android.content.Context

From class java.lang.Object

Object	clone () Creates and returns a copy of this `Object` .
boolean	equals ( Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize () Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class <?>	getClass () Returns the unique instance of `Class` that represents this object's class.
int	hashCode () Returns an integer hash code for this object.
final void	notify () Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll () Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString () Returns a string containing a concise, human-readable description of this object.
final void	wait () Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait (long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait (long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

From interface android.content.ComponentCallbacks

From interface android.content.ComponentCallbacks2

Constants

public static final String SERVICE_INTERFACE

Added in API level 19

The Intent action that must be declared as handled by the service.

Constant Value: "android.nfc.cardemulation.action.OFF_HOST_APDU_SERVICE"

public static final String SERVICE_META_DATA

Added in API level 19

The name of the meta-data element that contains more information about this service.

Constant Value: "android.nfc.cardemulation.off_host_apdu_service"

Public Constructors

public OffHostApduService ()

Added in API level 19

Public Methods

public abstract IBinder onBind ( Intent intent)

Added in API level 19

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 HostApduService ), or to an off-host execution environment (in case the user preferred a 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.

Parameters

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

Return an IBinder through which clients can call on to the service.

Results

Classes

OffHostApduService

Class Overview

Developer Guide

NFC Protocols

Service selection

AID groups

AID groups and categories

Service AID registration

Summary

Constants

public static final String SERVICE_INTERFACE

public static final String SERVICE_META_DATA

Public Constructors

public OffHostApduService ()

Public Methods

public abstract IBinder onBind ( Intent intent)

Parameters

Returns