public class Nfc

  1. Object
  2. Nfc

Entry point for the Codename One NFC API – read and write NDEF messages, exchange APDUs with smart cards, and host-emulate as a contactless card. Obtain the platform implementation via getInstance(); the returned subclass is owned by the active port.

Quick start: Read an NDEF URI

Nfc nfc = Nfc.getInstance();
if (!nfc.canRead()) {
    // device has no NFC or it is disabled
    return;
}
nfc.readTag(new NfcReadOptions()
        .setNdefOnly(true)
        .setAlertMessage("Hold near the poster"))
   .onResult((tag, err) -> {
        if (err != null) {
            return;
        }
        tag.readNdef().onResult((msg, e) -> {
            if (e == null) {
                String url = msg.getFirstRecord().getUriPayload();
                // launch / display url
            }
        });
   });

Quick start: Send an APDU to a smart card

nfc.readTag(new NfcReadOptions()
        .setTechFilter(TagType.ISO_DEP)
        .setIsoSelectAids(myAid))
   .onResult((tag, err) -> {
        if (err != null) return;
        IsoDep iso = tag.getIsoDep();
        if (iso == null) return;
        iso.transceive(myCommandApdu).onResult((resp, e) -> {
            if (ApduResponse.isSuccess(resp)) { ... }
        });
   });

Quick start: Host card emulation

class MyService extends HostCardEmulationService {
    public String[] getAids() { return new String[] { "F0010203040506" }; }
    public byte[] processCommand(byte[] apdu) {
        return ApduResponse.withStatus(new byte[] { 'O', 'K' },
                ApduResponse.swSuccess());
    }
}
Nfc.getInstance().registerHostCardEmulationService(new MyService());

Platform support

  • AndroidNfcAdapter foreground dispatch / reader-mode + HostApduService for HCE. Both manifest entries are auto-injected by the Maven plugin and the build daemon when this class is referenced.
  • iOSCore NFC (NFCNDEFReaderSession, NFCTagReaderSession) for reading; CardSession (iOS 17.4+, EU only) for HCE. The NFCReaderUsageDescription plist entry and the relevant entitlements are auto-injected by IPhoneBuilder.
  • JavaSE simulator – the Simulate -> NFC menu lets you tap a virtual tag, edit its NDEF payload, and fire APDUs at any registered HostCardEmulationService.
  • All other platforms (desktop deploy, JavaScript, …) – this base class is returned as-is and reports the device as unsupported; every operation completes with NfcError.NOT_AVAILABLE.

Constructors

protected Nfc()Ports construct subclasses.

Methods

public static Nfc getInstance()Returns the platform-specific singleton owned by the current port.
public boolean isSupported()true when NFC hardware is present, regardless of whether it is currently enabled.
public boolean canRead()true when NFC is supported AND currently enabled (Android setting toggle on, iOS Core NFC available).
public boolean canWrite()true when NFC writing is supported on this device.
public boolean canHostEmulate()true when this device can act as a host-emulated contactless card.
public AsyncResource<Tag> readTag(NfcReadOptions options)Performs a single tag-read session.
public AsyncResource<NdefMessage> readNdef(NfcReadOptions options)Convenience for readTag(new NfcReadOptions().setNdefOnly(true)) followed by Tag.readNdef().
public AsyncResource<Boolean> writeNdef(NfcReadOptions options, NdefMessage message)Convenience writer – opens a tag-read session, writes the given message and resolves with true.
public boolean stopRead()Cancels any in-flight readTag(NfcReadOptions) / readNdef(NfcReadOptions) / writeNdef(NfcReadOptions, NdefMessage) call.
public void addTagListener(NfcListener listener)Registers a long-running tag-discovery listener – useful on Android reader-mode where multiple tags can be tapped in succession.
public void removeTagListener(NfcListener listener)Removes a listener previously added via addTagListener(NfcListener).
public void registerHostCardEmulationService(HostCardEmulationService service)Registers a Host Card Emulation service.
public void unregisterHostCardEmulationService()Removes a previously registered HCE service.

Inherited methods

Constructor details

Nfc

protected Nfc()
Ports construct subclasses. Application code obtains the active instance via getInstance().

Method details

getInstance

public static Nfc getInstance()
Returns the platform-specific singleton owned by the current port. On ports that do not implement NFC this returns a base Nfc instance whose methods report the device as unsupported; calling code never needs a null check or a platform-specific if.

isSupported

public boolean isSupported()
true when NFC hardware is present, regardless of whether it is currently enabled. Combine with canRead() to drive UI affordances. Returns false on the fallback base class.

canRead

public boolean canRead()
true when NFC is supported AND currently enabled (Android setting toggle on, iOS Core NFC available). Defaults to false.

canWrite

public boolean canWrite()
true when NFC writing is supported on this device. On Android this mirrors canRead(); on iOS, writing requires iOS 13+ and the NFCReaderUsageDescription plist entry. Defaults to false.

canHostEmulate

public boolean canHostEmulate()

true when this device can act as a host-emulated contactless card. Android requires FEATURE_NFC_HOST_CARD_EMULATION; iOS 17.4

  • EU only with the HCE entitlement. Defaults to false.

readTag

public AsyncResource<Tag> readTag(NfcReadOptions options)

Performs a single tag-read session. Resolves with the discovered Tag (call Tag.readNdef() or one of the technology accessors) or fails with an NfcException. The base class fails immediately with NfcError.NOT_AVAILABLE.

Cancel an in-flight read via stopRead().

readNdef

public AsyncResource<NdefMessage> readNdef(NfcReadOptions options)
Convenience for readTag(new NfcReadOptions().setNdefOnly(true)) followed by Tag.readNdef(). Resolves with the parsed NDEF message, or fails with an NfcException.

writeNdef

public AsyncResource<Boolean> writeNdef(NfcReadOptions options, NdefMessage message)
Convenience writer – opens a tag-read session, writes the given message and resolves with true. Fails with NfcError.READ_ONLY for locked tags and with NfcError.CAPACITY_EXCEEDED when the message is too large.

stopRead

public boolean stopRead()
Cancels any in-flight readTag(NfcReadOptions) / readNdef(NfcReadOptions) / writeNdef(NfcReadOptions, NdefMessage) call. The pending AsyncResource completes with NfcError.USER_CANCELED.

Returns

true when a call was cancelled; false when no session was pending. Always false on the fallback base class.

addTagListener

public void addTagListener(NfcListener listener)

Registers a long-running tag-discovery listener – useful on Android reader-mode where multiple tags can be tapped in succession. Each new tag calls NfcListener.tagDiscovered(Tag) from the EDT.

Ports that do not support multi-shot reading fall back to a single-shot readTag(NfcReadOptions) each time – iOS for example dismisses the system sheet after the first tag and re-prompts.

No-op on the fallback base class.

removeTagListener

public void removeTagListener(NfcListener listener)
Removes a listener previously added via addTagListener(NfcListener). No-op on the fallback base class.

registerHostCardEmulationService

public void registerHostCardEmulationService(HostCardEmulationService service)

Registers a Host Card Emulation service. Only one service may be registered per app, and only the AIDs reported by HostCardEmulationService.getAids() are routed to it.

On Android the platform routing tables are populated from the service’s manifest entry; the Codename One Maven plugin and BuildDaemon auto-generate that entry from the AIDs at build time. At runtime this method simply hands the live instance to the port so APDUs can be dispatched.

No-op on the fallback base class.

unregisterHostCardEmulationService

public void unregisterHostCardEmulationService()
Removes a previously registered HCE service. No-op on the fallback base class.