FileDocCategorySizeDatePackage
Ndef.javaAPI DocAndroid 5.1 API14991Thu Mar 12 22:22:10 GMT 2015android.nfc.tech

Ndef

public final class Ndef extends BasicTagTechnology
Provides access to NDEF content and operations on a {@link Tag}.

Acquire a {@link Ndef} object using {@link #get}.

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

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

  • NFC Forum Type 1 Tag ({@link #NFC_FORUM_TYPE_1}), such as the Innovision Topaz
  • NFC Forum Type 2 Tag ({@link #NFC_FORUM_TYPE_2}), such as the NXP MIFARE Ultralight
  • NFC Forum Type 3 Tag ({@link #NFC_FORUM_TYPE_3}), such as Sony Felica
  • NFC Forum Type 4 Tag ({@link #NFC_FORUM_TYPE_4}), such as NXP MIFARE Desfire
It is mandatory for all Android devices with NFC to correctly enumerate {@link Ndef} on NFC Forum Tag Types 1-4, and implement all NDEF operations as defined in this class.

Some vendors have there 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 {@link Ndef} under these vendor specifications where possible, but it is not mandatory. {@link #getType} returns a String describing this specification, for example {@link #MIFARE_CLASSIC} is com.nxp.ndef.mifareclassic.

Android devices that support MIFARE Classic must also correctly implement {@link 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 {@link android.Manifest.permission#NFC} permission.

Fields Summary
private static final String
TAG
public static final int
NDEF_MODE_READ_ONLY
public static final int
NDEF_MODE_READ_WRITE
public static final int
NDEF_MODE_UNKNOWN
public static final String
EXTRA_NDEF_MSG
public static final String
EXTRA_NDEF_MAXLENGTH
public static final String
EXTRA_NDEF_CARDSTATE
public static final String
EXTRA_NDEF_TYPE
public static final int
TYPE_OTHER
public static final int
TYPE_1
public static final int
TYPE_2
public static final int
TYPE_3
public static final int
TYPE_4
public static final int
TYPE_MIFARE_CLASSIC
public static final int
TYPE_ICODE_SLI
public static final String
UNKNOWN
public static final String
NFC_FORUM_TYPE_1
NFC Forum Tag Type 1
public static final String
NFC_FORUM_TYPE_2
NFC Forum Tag Type 2
public static final String
NFC_FORUM_TYPE_3
NFC Forum Tag Type 4
public static final String
NFC_FORUM_TYPE_4
NFC Forum Tag Type 4
public static final String
MIFARE_CLASSIC
NDEF on MIFARE Classic
public static final String
ICODE_SLI
NDEF on iCODE SLI
private final int
mMaxNdefSize
private final int
mCardState
private final android.nfc.NdefMessage
mNdefMsg
private final int
mNdefType
Constructors Summary
public Ndef(android.nfc.Tag tag)
Internal constructor, to be used by NfcAdapter

hide

        super(tag, TagTechnology.NDEF);
        Bundle extras = tag.getTechExtras(TagTechnology.NDEF);
        if (extras != null) {
            mMaxNdefSize = extras.getInt(EXTRA_NDEF_MAXLENGTH);
            mCardState = extras.getInt(EXTRA_NDEF_CARDSTATE);
            mNdefMsg = extras.getParcelable(EXTRA_NDEF_MSG);
            mNdefType = extras.getInt(EXTRA_NDEF_TYPE);
        } else {
            throw new NullPointerException("NDEF tech extras are null.");
        }
Methods Summary
public booleancanMakeReadOnly()
Indicates whether a tag can be made read-only with {@link #makeReadOnly()}.

Does not cause any RF activity and does not block.

return
true if it is possible to make this tag read-only

        INfcTag tagService = mTag.getTagService();
        if (tagService == null) {
            return false;
        }
        try {
            return tagService.canMakeReadOnly(mNdefType);
        } catch (RemoteException e) {
            Log.e(TAG, "NFC service dead", e);
            return false;
        }
public static android.nfc.tech.Ndefget(android.nfc.Tag tag)
Get an instance of {@link Ndef} for the given tag.

Returns null if {@link Ndef} was not enumerated in {@link 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.

param
tag an NDEF compatible tag
return
Ndef object


                                                                            
         
        if (!tag.hasTech(TagTechnology.NDEF)) return null;
        try {
            return new Ndef(tag);
        } catch (RemoteException e) {
            return null;
        }
public android.nfc.NdefMessagegetCachedNdefMessage()
Get the {@link 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
NDEF Message read from the tag at discovery time, can be null

        return mNdefMsg;
public intgetMaxSize()
Get the maximum NDEF message size in bytes.

Does not cause any RF activity and does not block.

return
size in bytes

        return mMaxNdefSize;
public android.nfc.NdefMessagegetNdefMessage()
Read the current {@link 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 {@link IOException} if {@link #close} is called from another thread.

Requires the {@link android.Manifest.permission#NFC} permission.

return
the NDEF Message, can be null
throws
TagLostException if the tag leaves the field
throws
IOException if there is an I/O failure, or the operation is canceled
throws
FormatException if the NDEF Message on the tag is malformed

        checkConnected();

        try {
            INfcTag tagService = mTag.getTagService();
            if (tagService == null) {
                throw new IOException("Mock tags don't support this operation.");
            }
            int serviceHandle = mTag.getServiceHandle();
            if (tagService.isNdef(serviceHandle)) {
                NdefMessage msg = tagService.ndefRead(serviceHandle);
                if (msg == null && !tagService.isPresent(serviceHandle)) {
                    throw new TagLostException();
                }
                return msg;
            } else if (!tagService.isPresent(serviceHandle)) {
                throw new TagLostException();
            } else {
                return null;
            }
        } catch (RemoteException e) {
            Log.e(TAG, "NFC service dead", e);
            return null;
        }
public java.lang.StringgetType()
Get the NDEF tag type.

Returns one of {@link #NFC_FORUM_TYPE_1}, {@link #NFC_FORUM_TYPE_2}, {@link #NFC_FORUM_TYPE_3}, {@link #NFC_FORUM_TYPE_4}, {@link #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
a string representing the NDEF tag type

        switch (mNdefType) {
            case TYPE_1:
                return NFC_FORUM_TYPE_1;
            case TYPE_2:
                return NFC_FORUM_TYPE_2;
            case TYPE_3:
                return NFC_FORUM_TYPE_3;
            case TYPE_4:
                return NFC_FORUM_TYPE_4;
            case TYPE_MIFARE_CLASSIC:
                return MIFARE_CLASSIC;
            case TYPE_ICODE_SLI:
                return ICODE_SLI;
            default:
                return UNKNOWN;
        }
public booleanisWritable()
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 {@link android.Manifest.permission#NFC} permission.

return
true if the tag is writable

        return (mCardState == NDEF_MODE_READ_WRITE);
public booleanmakeReadOnly()
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 {@link IOException} if {@link #close} is called from another thread.

Requires the {@link android.Manifest.permission#NFC} permission.

return
true on success, false if it is not possible to make this tag read-only
throws
TagLostException if the tag leaves the field
throws
IOException if there is an I/O failure, or the operation is canceled

        checkConnected();

        try {
            INfcTag tagService = mTag.getTagService();
            if (tagService == null) {
                return false;
            }
            if (tagService.isNdef(mTag.getServiceHandle())) {
                int errorCode = tagService.ndefMakeReadOnly(mTag.getServiceHandle());
                switch (errorCode) {
                    case ErrorCodes.SUCCESS:
                        return true;
                    case ErrorCodes.ERROR_IO:
                        throw new IOException();
                    case ErrorCodes.ERROR_INVALID_PARAM:
                        return false;
                    default:
                        // Should not happen
                        throw new IOException();
                }
           }
           else {
               throw new IOException("Tag is not ndef");
           }
        } catch (RemoteException e) {
            Log.e(TAG, "NFC service dead", e);
            return false;
        }
public voidwriteNdefMessage(android.nfc.NdefMessage msg)
Overwrite the {@link 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 {@link IOException} if {@link #close} is called from another thread.

Requires the {@link android.Manifest.permission#NFC} permission.

param
msg the NDEF Message to write, must not be null
throws
TagLostException if the tag leaves the field
throws
IOException if there is an I/O failure, or the operation is canceled
throws
FormatException if the NDEF Message to write is malformed

        checkConnected();

        try {
            INfcTag tagService = mTag.getTagService();
            if (tagService == null) {
                throw new IOException("Mock tags don't support this operation.");
            }
            int serviceHandle = mTag.getServiceHandle();
            if (tagService.isNdef(serviceHandle)) {
                int errorCode = tagService.ndefWrite(serviceHandle, msg);
                switch (errorCode) {
                    case ErrorCodes.SUCCESS:
                        break;
                    case ErrorCodes.ERROR_IO:
                        throw new IOException();
                    case ErrorCodes.ERROR_INVALID_PARAM:
                        throw new FormatException();
                    default:
                        // Should not happen
                        throw new IOException();
                }
            }
            else {
                throw new IOException("Tag is not ndef");
            }
        } catch (RemoteException e) {
            Log.e(TAG, "NFC service dead", e);
        }