* {@link Tag} is an immutable object that represents the state of a NFC tag at * the time of discovery. It can be used as a handle to {@link TagTechnology} classes * to perform advanced operations, or directly queried for its ID via {@link #getId} and the * set of technologies it contains via {@link #getTechList}. Arrays passed to and * returned by this class are not cloned, so be careful not to modify them. *
* A new tag object is created every time a tag is discovered (comes into range), even * if it is the same physical tag. If a tag is removed and then returned into range, then * only the most recent tag object can be successfully used to create a {@link TagTechnology}. * *
The Tag dispatch mechanism was designed to give a high probability of dispatching * a tag to the correct activity without showing the user an activity chooser dialog. * This is important for NFC interactions because they are very transient -- if a user has to * move the Android device to choose an application then the connection will likely be broken. * *
* Tags can have a wide range of capabilities. Simple tags just offer read/write semantics, * and contain some one time * programmable areas to make read-only. More complex tags offer math operations * and per-sector access control and authentication. The most sophisticated tags * contain operating environments allowing complex interactions with the * code executing on the tag. Use {@link TagTechnology} classes to access a broad * range of capabilities available in NFC tags. *
*/ public final class Tag implements Parcelable { final byte[] mId; final int[] mTechList; final String[] mTechStringList; final Bundle[] mTechExtras; final int mServiceHandle; // for use by NFC service, 0 indicates a mock final INfcTag mTagService; // interface to NFC service, will be null if mock tag int mConnectedTechnology; /** * Hidden constructor to be used by NFC service and internal classes. * @hide */ public Tag(byte[] id, int[] techList, Bundle[] techListExtras, int serviceHandle, INfcTag tagService) { if (techList == null) { throw new IllegalArgumentException("rawTargets cannot be null"); } mId = id; mTechList = Arrays.copyOf(techList, techList.length); mTechStringList = generateTechStringList(techList); // Ensure mTechExtras is as long as mTechList mTechExtras = Arrays.copyOf(techListExtras, techList.length); mServiceHandle = serviceHandle; mTagService = tagService; mConnectedTechnology = -1; } /** * Construct a mock Tag. *
This is an application constructed tag, so NfcAdapter methods on this Tag may fail * with {@link IllegalArgumentException} since it does not represent a physical Tag. *
This constructor might be useful for mock testing.
* @param id The tag identifier, can be null
* @param techList must not be null
* @return freshly constructed tag
* @hide
*/
public static Tag createMockTag(byte[] id, int[] techList, Bundle[] techListExtras) {
// set serviceHandle to 0 and tagService to null to indicate mock tag
return new Tag(id, techList, techListExtras, 0, null);
}
private String[] generateTechStringList(int[] techList) {
final int size = techList.length;
String[] strings = new String[size];
for (int i = 0; i < size; i++) {
switch (techList[i]) {
case TagTechnology.ISO_DEP:
strings[i] = IsoDep.class.getName();
break;
case TagTechnology.MIFARE_CLASSIC:
strings[i] = MifareClassic.class.getName();
break;
case TagTechnology.MIFARE_ULTRALIGHT:
strings[i] = MifareUltralight.class.getName();
break;
case TagTechnology.NDEF:
strings[i] = Ndef.class.getName();
break;
case TagTechnology.NDEF_FORMATABLE:
strings[i] = NdefFormatable.class.getName();
break;
case TagTechnology.NFC_A:
strings[i] = NfcA.class.getName();
break;
case TagTechnology.NFC_B:
strings[i] = NfcB.class.getName();
break;
case TagTechnology.NFC_F:
strings[i] = NfcF.class.getName();
break;
case TagTechnology.NFC_V:
strings[i] = NfcV.class.getName();
break;
case TagTechnology.NFC_BARCODE:
strings[i] = NfcBarcode.class.getName();
break;
default:
throw new IllegalArgumentException("Unknown tech type " + techList[i]);
}
}
return strings;
}
static int[] getTechCodesFromStrings(String[] techStringList) throws IllegalArgumentException {
if (techStringList == null) {
throw new IllegalArgumentException("List cannot be null");
}
int[] techIntList = new int[techStringList.length];
HashMap The tag identifier is a low level serial number, used for anti-collision
* and identification.
* Most tags have a stable unique identifier
* (UID), but some tags will generate a random ID every time they are discovered
* (RID), and there are some tags with no ID at all (the byte array will be zero-sized).
* The size and format of an ID is specific to the RF technology used by the tag.
* This function retrieves the ID as determined at discovery time, and does not
* perform any further RF communication or block.
* @return ID as byte array, never null
*/
public byte[] getId() {
return mId;
}
/**
* Get the technologies available in this tag, as fully qualified class names.
*
* A technology is an implementation of the {@link TagTechnology} interface,
* and can be instantiated by calling the static
* Android defines a mandatory set of technologies that must be correctly
* enumerated by all Android NFC devices, and an optional
* set of proprietary technologies.
* See {@link TagTechnology} for more details.
*
* The ordering of the returned array is undefined and should not be relied upon.
* @return an array of fully-qualified {@link TagTechnology} class-names.
*/
public String[] getTechList() {
return mTechStringList;
}
/**
* Rediscover the technologies available on this tag.
*
* The technologies that are available on a tag may change due to
* operations being performed on a tag. For example, formatting a
* tag as NDEF adds the {@link Ndef} technology. The {@link rediscover}
* method reenumerates the available technologies on the tag
* and returns a new {@link Tag} object containing these technologies.
*
* You may not be connected to any of this {@link Tag}'s technologies
* when calling this method.
* This method guarantees that you will be returned the same Tag
* if it is still in the field.
* May cause RF activity and may block. Must not be called
* from the main application thread. A blocked call will be canceled with
* {@link IOException} by calling {@link #close} from another thread.
* Does not remove power from the RF field, so a tag having a random
* ID should not change its ID.
* @return the rediscovered tag object.
* @throws IOException if the tag cannot be rediscovered
* @hide
*/
// TODO See if we need TagLostException
// TODO Unhide for ICS
// TODO Update documentation to make sure it matches with the final
// implementation.
public Tag rediscover() throws IOException {
if (getConnectedTechnology() != -1) {
throw new IllegalStateException("Close connection to the technology first!");
}
if (mTagService == null) {
throw new IOException("Mock tags don't support this operation.");
}
try {
Tag newTag = mTagService.rediscover(getServiceHandle());
if (newTag != null) {
return newTag;
} else {
throw new IOException("Failed to rediscover tag");
}
} catch (RemoteException e) {
throw new IOException("NFC service dead");
}
}
/** @hide */
public boolean hasTech(int techType) {
for (int tech : mTechList) {
if (tech == techType) return true;
}
return false;
}
/** @hide */
public Bundle getTechExtras(int tech) {
int pos = -1;
for (int idx = 0; idx < mTechList.length; idx++) {
if (mTechList[idx] == tech) {
pos = idx;
break;
}
}
if (pos < 0) {
return null;
}
return mTechExtras[pos];
}
/** @hide */
public INfcTag getTagService() {
return mTagService;
}
/**
* Human-readable description of the tag, for debugging.
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder("TAG: Tech [");
String[] techList = getTechList();
int length = techList.length;
for (int i = 0; i < length; i++) {
sb.append(techList[i]);
if (i < length - 1) {
sb.append(", ");
}
}
sb.append("]");
return sb.toString();
}
/*package*/ static byte[] readBytesWithNull(Parcel in) {
int len = in.readInt();
byte[] result = null;
if (len >= 0) {
result = new byte[len];
in.readByteArray(result);
}
return result;
}
/*package*/ static void writeBytesWithNull(Parcel out, byte[] b) {
if (b == null) {
out.writeInt(-1);
return;
}
out.writeInt(b.length);
out.writeByteArray(b);
}
@Override
public int describeContents() {
return 0;
}
@Override
public void writeToParcel(Parcel dest, int flags) {
// Null mTagService means this is a mock tag
int isMock = (mTagService == null)?1:0;
writeBytesWithNull(dest, mId);
dest.writeInt(mTechList.length);
dest.writeIntArray(mTechList);
dest.writeTypedArray(mTechExtras, 0);
dest.writeInt(mServiceHandle);
dest.writeInt(isMock);
if (isMock == 0) {
dest.writeStrongBinder(mTagService.asBinder());
}
}
public static final Parcelable.Creatorget(Tag)
* method on the implementation with this Tag. The {@link TagTechnology}
* object can then be used to perform advanced, technology-specific operations on a tag.
*