HostNfcFService

public abstract class HostNfcFService
extends Service

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


HostNfcFService is a convenience Service class that can be extended to emulate an NFC-F card inside an Android service component.

NFC Protocols

Cards emulated by this class are based on the NFC-Forum NFC-F protocol (based on the JIS-X 6319-4 specification.)

System Code and NFCID2 registration

A HostNfcFService service can register exactly one System Code and one NFCID2. For details about the use of System Code and NFCID2, see the NFC Forum Digital specification.

To statically register a System Code and NFCID2 with the service, a SERVICE_META_DATA entry must be included in the declaration of the service.

All HostNfcFService declarations in the manifest must require the Manifest.permission.BIND_NFC_SERVICE permission in their <service> tag, to ensure that only the platform can bind to your service.

An example of a HostNfcFService manifest declaration is shown below:

 <service android:name=".MyHostNfcFService" android:exported="true" android:permission="android.permission.BIND_NFC_SERVICE">
     <intent-filter>
         <action android:name="android.nfc.cardemulation.action.HOST_NFCF_SERVICE"/>
     </intent-filter>
     <meta-data android:name="android.nfc.cardemulation.host_nfcf_service" android:resource="@xml/nfcfservice"/>
 </service>
This meta-data tag points to an nfcfservice.xml file. An example of this file with a System Code and NFCID2 declaration is shown below:
 <host-nfcf-service xmlns:android="http://schemas.android.com/apk/res/android"
           android:description="@string/servicedesc">
       <system-code-filter android:name="4000"/>
       <nfcid2-filter android:name="02FE000000000000"/>
       <t3tPmm-filter android:name="FFFFFFFFFFFFFFFF"/>
 </host-nfcf-service>
 

The <host-nfcf-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 <host-nfcf-service> must contain:

Alternatively, the System Code and NFCID2 can be dynamically registererd for a service by using the NfcFCardEmulation#registerSystemCodeForService(ComponentName, String) and NfcFCardEmulation#setNfcid2ForService(ComponentName, String) methods.

Service selection

When a remote NFC devices wants to communicate with your service, it sends a SENSF_REQ command to the NFC controller, requesting a System Code. If a NfcFCardEmulation service has registered this system code and has been enabled by the foreground application, the NFC controller will respond with the NFCID2 that is registered for this service. The reader can then continue data exchange with this service by using the NFCID2.

Data exchange

After service selection, all frames addressed to the NFCID2 of this service will be sent through processNfcFPacket(byte[], android.os.Bundle), until the NFC link is broken.

When the NFC link is broken, onDeactivated(int) will be called.

Summary

Constants

int DEACTIVATION_LINK_LOSS

Reason for onDeactivated(int).

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.

Inherited constants

Public constructors

HostNfcFService()

Public methods

final IBinder onBind(Intent intent)

Return the communication channel to the service.

abstract void onDeactivated(int reason)

This method will be called in following possible scenarios:

  • The NFC link has been lost

  • abstract byte[] processNfcFPacket(byte[] commandPacket, Bundle extras)

    This method will be called when a NFC-F packet has been received from a remote device.

    final void sendResponsePacket(byte[] responsePacket)

    Sends a response packet back to the remote device.

    Inherited methods

    Constants

    Added in API level 24
    public static final int DEACTIVATION_LINK_LOSS

    Reason for onDeactivated(int). Indicates deactivation was due to the NFC link being lost.

    Constant Value: 0 (0x00000000)

    SERVICE_INTERFACE

    Added in API level 24
    public static final String SERVICE_INTERFACE

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

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

    SERVICE_META_DATA

    Added in API level 24
    public static final String SERVICE_META_DATA

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

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

    Public constructors

    HostNfcFService

    Added in API level 24
    public HostNfcFService ()

    Public methods

    onBind

    Added in API level 24
    public final 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

    Added in API level 24
    public abstract void onDeactivated (int reason)

    This method will be called in following possible scenarios:

  • The NFC link has been lost

    Parameters
    reason int: DEACTIVATION_LINK_LOSS

  • processNfcFPacket

    Added in API level 24
    public abstract byte[] processNfcFPacket (byte[] commandPacket, 
                    Bundle extras)

    This method will be called when a NFC-F packet has been received from a remote device. A response packet can be provided directly by returning a byte-array in this method. Note that in general response packets must be sent as quickly as possible, given the fact that the user is likely holding their device over an NFC reader when this method is called.

    This method is running on the main thread of your application. If you cannot return a response packet immediately, return null and use the sendResponsePacket(byte[]) method later.

    Parameters
    commandPacket byte: The NFC-F packet 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 packet, or null if no response packet can be sent at this point.

    sendResponsePacket

    Added in API level 24
    public final void sendResponsePacket (byte[] responsePacket)

    Sends a response packet back to the remote device.

    Note: this method may be called from any thread and will not block.

    Parameters
    responsePacket byte: A byte-array containing the response packet.