Added in API level 24

HostNfcFService


abstract class HostNfcFService : Service
kotlin.Any
   ↳ 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 android.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
static Int

Reason for onDeactivated(int).

static String

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

static String

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

Inherited constants
Public constructors

Public methods
IBinder?
onBind(intent: Intent!)

abstract Unit
onDeactivated(reason: Int)

This method will be called in following possible scenarios:

  • The NFC link has been lost
  • abstract ByteArray!
    processNfcFPacket(commandPacket: ByteArray!, extras: Bundle!)

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

    Unit
    sendResponsePacket(responsePacket: ByteArray!)

    Sends a response packet back to the remote device.

    Inherited functions

    Constants

    Added in API level 24
    static val DEACTIVATION_LINK_LOSS: Int

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

    Value: 0

    SERVICE_INTERFACE

    Added in API level 24
    static val SERVICE_INTERFACE: String

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

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

    SERVICE_META_DATA

    Added in API level 24
    static val SERVICE_META_DATA: String

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

    Value: "android.nfc.cardemulation.host_nfcf_service"

    Public constructors

    HostNfcFService

    Added in API level 24
    HostNfcFService()

    Public methods

    onBind

    Added in API level 24
    fun onBind(intent: Intent!): IBinder?
    Parameters
    intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
    Return
    IBinder? Return an IBinder through which clients can call on to the service.

    onDeactivated

    Added in API level 24
    abstract fun onDeactivated(reason: Int): Unit

    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
    abstract fun processNfcFPacket(
        commandPacket: ByteArray!,
        extras: Bundle!
    ): ByteArray!

    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 ByteArray!: The NFC-F packet that was received from the remote device
    extras Bundle!: A bundle containing extra data. May be null.
    Return
    ByteArray! 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
    fun sendResponsePacket(responsePacket: ByteArray!): Unit

    Sends a response packet back to the remote device.

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

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