Added in API level 10

Ndef

class Ndef : TagTechnology
kotlin.Any
   ↳ android.nfc.tech.Ndef

Provides access to NDEF content and operations on a Tag.

Acquire a Ndef object using get.

NDEF is an NFC Forum data format. The data formats are implemented in android.nfc.NdefMessage and android.nfc.NdefRecord. This class provides methods to retrieve and modify the android.nfc.NdefMessage on a tag.

There are currently four NFC Forum standardized tag types that can be formatted to contain NDEF data.

It is mandatory for all Android devices with NFC to correctly enumerate Ndef on NFC Forum Tag Types 1-4, and implement all NDEF operations as defined in this class.

Some vendors have their own well defined specifications for storing NDEF data on tags that do not fall into the above categories. Android devices with NFC should enumerate and implement Ndef under these vendor specifications where possible, but it is not mandatory. getType returns a String describing this specification, for example MIFARE_CLASSIC is com.nxp.ndef.mifareclassic.

Android devices that support MIFARE Classic must also correctly implement Ndef on MIFARE Classic tags formatted to NDEF.

For guaranteed compatibility across all Android devices with NFC, it is recommended to use NFC Forum Types 1-4 in new deployments of NFC tags with NDEF payload. Vendor NDEF formats will not work on all Android devices.

Note: Methods that perform I/O operations require the android.Manifest.permission#NFC permission.

Summary

Constants
static String

NDEF on MIFARE Classic

static String

NFC Forum Tag Type 1

static String

NFC Forum Tag Type 2

static String

NFC Forum Tag Type 3

static String

NFC Forum Tag Type 4

Public methods
Boolean

Indicates whether a tag can be made read-only with makeReadOnly().

Unit

Unit

static Ndef!
get(tag: Tag!)

Get an instance of Ndef for the given tag.

NdefMessage!

Get the NdefMessage that was read from the tag at discovery time.

Int

Get the maximum NDEF message size in bytes.

NdefMessage!

Read the current android.nfc.NdefMessage on this tag.

Tag!

String!

Get the NDEF tag type.

Boolean

Boolean

Determine if the tag is writable.

Boolean

Make a tag read-only.

Unit

Overwrite the NdefMessage on this tag.

Constants

MIFARE_CLASSIC

Added in API level 10
static val MIFARE_CLASSIC: String

NDEF on MIFARE Classic

Value: "com.nxp.ndef.mifareclassic"

NFC_FORUM_TYPE_1

Added in API level 10
static val NFC_FORUM_TYPE_1: String

NFC Forum Tag Type 1

Value: "org.nfcforum.ndef.type1"

NFC_FORUM_TYPE_2

Added in API level 10
static val NFC_FORUM_TYPE_2: String

NFC Forum Tag Type 2

Value: "org.nfcforum.ndef.type2"

NFC_FORUM_TYPE_3

Added in API level 10
static val NFC_FORUM_TYPE_3: String

NFC Forum Tag Type 3

Value: "org.nfcforum.ndef.type3"

NFC_FORUM_TYPE_4

Added in API level 10
static val NFC_FORUM_TYPE_4: String

NFC Forum Tag Type 4

Value: "org.nfcforum.ndef.type4"

Public methods

canMakeReadOnly

Added in API level 10
fun canMakeReadOnly(): Boolean

Indicates whether a tag can be made read-only with makeReadOnly().

Does not cause any RF activity and does not block.

Return
Boolean true if it is possible to make this tag read-only
Exceptions
java.lang.SecurityException if the tag object is reused after the tag has left the field

close

Added in API level 10
fun close(): Unit
Exceptions
java.lang.Exception if this resource cannot be closed
java.io.IOException if an I/O error occurs
java.lang.SecurityException if the tag object is reused after the tag has left the field

connect

Added in API level 10
fun connect(): Unit
Exceptions
TagLostException if the tag leaves the field
java.io.IOException if there is an I/O failure, or connect is canceled
java.lang.SecurityException if the tag object is reused after the tag has left the field

get

Added in API level 10
static fun get(tag: Tag!): Ndef!

Get an instance of Ndef for the given tag.

Returns null if Ndef was not enumerated in Tag#getTechList. This indicates the tag is not NDEF formatted, or that this tag is NDEF formatted but under a vendor specification that this Android device does not implement.

Does not cause any RF activity and does not block.

Parameters
tag Tag!: an NDEF compatible tag
Return
Ndef! Ndef object

getCachedNdefMessage

Added in API level 10
fun getCachedNdefMessage(): NdefMessage!

Get the NdefMessage that was read from the tag at discovery time.

If the NDEF Message is modified by an I/O operation then it will not be updated here, this function only returns what was discovered when the tag entered the field.

Note that this method may return null if the tag was in the INITIALIZED state as defined by NFC Forum, as in this state the tag is formatted to support NDEF but does not contain a message yet.

Does not cause any RF activity and does not block.

Return
NdefMessage! NDEF Message read from the tag at discovery time, can be null

getMaxSize

Added in API level 10
fun getMaxSize(): Int

Get the maximum NDEF message size in bytes.

Does not cause any RF activity and does not block.

Return
Int size in bytes

getNdefMessage

Added in API level 10
fun getNdefMessage(): NdefMessage!

Read the current android.nfc.NdefMessage on this tag.

This always reads the current NDEF Message stored on the tag.

Note that this method may return null if the tag was in the INITIALIZED state as defined by NFC Forum, as in that state the tag is formatted to support NDEF but does not contain a message yet.

This is an I/O operation and will block until complete. It must not be called from the main application thread. A blocked call will be canceled with IOException if #close is called from another thread.

Requires the android.Manifest.permission#NFC permission.

Return
NdefMessage! the NDEF Message, can be null
Exceptions
android.nfc.TagLostException if the tag leaves the field
java.io.IOException if there is an I/O failure, or the operation is canceled
android.nfc.FormatException if the NDEF Message on the tag is malformed
java.lang.SecurityException if the tag object is reused after the tag has left the field

getTag

Added in API level 10
fun getTag(): Tag!
Return
Tag! the Tag backing this TagTechnology object.

getType

Added in API level 10
fun getType(): String!

Get the NDEF tag type.

Returns one of NFC_FORUM_TYPE_1, NFC_FORUM_TYPE_2, NFC_FORUM_TYPE_3, NFC_FORUM_TYPE_4, MIFARE_CLASSIC or another NDEF tag type that has not yet been formalized in this Android API.

Does not cause any RF activity and does not block.

Return
String! a string representing the NDEF tag type

isConnected

Added in API level 10
fun isConnected(): Boolean
Return
Boolean true if I/O operations should be possible

isWritable

Added in API level 10
fun isWritable(): Boolean

Determine if the tag is writable.

NFC Forum tags can be in read-only or read-write states.

Does not cause any RF activity and does not block.

Requires android.Manifest.permission#NFC permission.

Return
Boolean true if the tag is writable

makeReadOnly

Added in API level 10
fun makeReadOnly(): Boolean

Make a tag read-only.

This sets the CC field to indicate the tag is read-only, and where possible permanently sets the lock bits to prevent any further modification of the memory.

This is a one-way process and cannot be reverted!

This is an I/O operation and will block until complete. It must not be called from the main application thread. A blocked call will be canceled with IOException if #close is called from another thread.

Requires the android.Manifest.permission#NFC permission.

Return
Boolean true on success, false if it is not possible to make this tag read-only
Exceptions
android.nfc.TagLostException if the tag leaves the field
java.io.IOException if there is an I/O failure, or the operation is canceled
java.lang.SecurityException if the tag object is reused after the tag has left the field

writeNdefMessage

Added in API level 10
fun writeNdefMessage(msg: NdefMessage!): Unit

Overwrite the NdefMessage on this tag.

This is an I/O operation and will block until complete. It must not be called from the main application thread. A blocked call will be canceled with IOException if #close is called from another thread.

Requires the android.Manifest.permission#NFC permission.

Parameters
msg NdefMessage!: the NDEF Message to write, must not be null
Exceptions
android.nfc.TagLostException if the tag leaves the field
java.io.IOException if there is an I/O failure, or the operation is canceled
android.nfc.FormatException if the NDEF Message to write is malformed
java.lang.SecurityException if the tag object is reused after the tag has left the field