Java tutorial
/* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.nfc; import android.annotation.UnsupportedAppUsage; import android.content.Context; import android.nfc.tech.IsoDep; import android.nfc.tech.MifareClassic; import android.nfc.tech.MifareUltralight; import android.nfc.tech.Ndef; import android.nfc.tech.NdefFormatable; import android.nfc.tech.NfcA; import android.nfc.tech.NfcB; import android.nfc.tech.NfcBarcode; import android.nfc.tech.NfcF; import android.nfc.tech.NfcV; import android.nfc.tech.TagTechnology; import android.os.Bundle; import android.os.Parcel; import android.os.Parcelable; import android.os.RemoteException; import java.io.IOException; import java.util.Arrays; import java.util.HashMap; /** * Represents an NFC tag that has been discovered. * <p> * {@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 <em>not</em> cloned, so be careful not to modify them. * <p> * 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}. * * <h3>Tag Dispatch</h3> * When a tag is discovered, a {@link Tag} object is created and passed to a * single activity via the {@link NfcAdapter#EXTRA_TAG} extra in an * {@link android.content.Intent} via {@link Context#startActivity}. A four stage dispatch is used * to select the * most appropriate activity to handle the tag. The Android OS executes each stage in order, * and completes dispatch as soon as a single matching activity is found. If there are multiple * matching activities found at any one stage then the Android activity chooser dialog is shown * to allow the user to select the activity to receive the tag. * * <p>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. * * <h4>1. Foreground activity dispatch</h4> * A foreground activity that has called * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} is * given priority. See the documentation on * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} for * its usage. * <h4>2. NDEF data dispatch</h4> * If the tag contains NDEF data the system inspects the first {@link NdefRecord} in the first * {@link NdefMessage}. If the record is a URI, SmartPoster, or MIME data * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_NDEF_DISCOVERED}. For URI * and SmartPoster records the URI is put into the intent's data field. For MIME records the MIME * type is put in the intent's type field. This allows activities to register to be launched only * when data they know how to handle is present on a tag. This is the preferred method of handling * data on a tag since NDEF data can be stored on many types of tags and doesn't depend on a * specific tag technology. * See {@link NfcAdapter#ACTION_NDEF_DISCOVERED} for more detail. If the tag does not contain * NDEF data, or if no activity is registered * for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI or MIME type then dispatch * moves to stage 3. * <h4>3. Tag Technology dispatch</h4> * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_TECH_DISCOVERED} to * dispatch the tag to an activity that can handle the technologies present on the tag. * Technologies are defined as sub-classes of {@link TagTechnology}, see the package * {@link android.nfc.tech}. The Android OS looks for an activity that can handle one or * more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED} for more detail. * <h4>4. Fall-back dispatch</h4> * If no activity has been matched then {@link Context#startActivity} is called with * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. This is intended as a fall-back mechanism. * See {@link NfcAdapter#ACTION_TAG_DISCOVERED}. * * <h3>NFC Tag Background</h3> * An NFC tag is a passive NFC device, powered by the NFC field of this Android device while * it is in range. Tag's can come in many forms, such as stickers, cards, key fobs, or * even embedded in a more sophisticated device. * <p> * 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. * <p> */ public final class Tag implements Parcelable { @UnsupportedAppUsage 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. * <p>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. * <p>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<String, Integer> stringToCodeMap = getTechStringToCodeMap(); for (int i = 0; i < techStringList.length; i++) { Integer code = stringToCodeMap.get(techStringList[i]); if (code == null) { throw new IllegalArgumentException("Unknown tech type " + techStringList[i]); } techIntList[i] = code.intValue(); } return techIntList; } private static HashMap<String, Integer> getTechStringToCodeMap() { HashMap<String, Integer> techStringToCodeMap = new HashMap<String, Integer>(); techStringToCodeMap.put(IsoDep.class.getName(), TagTechnology.ISO_DEP); techStringToCodeMap.put(MifareClassic.class.getName(), TagTechnology.MIFARE_CLASSIC); techStringToCodeMap.put(MifareUltralight.class.getName(), TagTechnology.MIFARE_ULTRALIGHT); techStringToCodeMap.put(Ndef.class.getName(), TagTechnology.NDEF); techStringToCodeMap.put(NdefFormatable.class.getName(), TagTechnology.NDEF_FORMATABLE); techStringToCodeMap.put(NfcA.class.getName(), TagTechnology.NFC_A); techStringToCodeMap.put(NfcB.class.getName(), TagTechnology.NFC_B); techStringToCodeMap.put(NfcF.class.getName(), TagTechnology.NFC_F); techStringToCodeMap.put(NfcV.class.getName(), TagTechnology.NFC_V); techStringToCodeMap.put(NfcBarcode.class.getName(), TagTechnology.NFC_BARCODE); return techStringToCodeMap; } /** * For use by NfcService only. * @hide */ @UnsupportedAppUsage public int getServiceHandle() { return mServiceHandle; } /** * For use by NfcService only. * @hide */ public int[] getTechCodeList() { return mTechList; } /** * Get the Tag Identifier (if it has one). * <p>The tag identifier is a low level serial number, used for anti-collision * and identification. * <p> 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). * <p> The size and format of an ID is specific to the RF technology used by the tag. * <p> 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. * <p> * A technology is an implementation of the {@link TagTechnology} interface, * and can be instantiated by calling the static <code>get(Tag)</code> * method on the implementation with this Tag. The {@link TagTechnology} * object can then be used to perform advanced, technology-specific operations on a tag. * <p> * 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. * <p> * 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. * <p> * 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. * <p> * 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. * <p>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. * <p>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 */ @UnsupportedAppUsage 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.Creator<Tag> CREATOR = new Parcelable.Creator<Tag>() { @Override public Tag createFromParcel(Parcel in) { INfcTag tagService; // Tag fields byte[] id = Tag.readBytesWithNull(in); int[] techList = new int[in.readInt()]; in.readIntArray(techList); Bundle[] techExtras = in.createTypedArray(Bundle.CREATOR); int serviceHandle = in.readInt(); int isMock = in.readInt(); if (isMock == 0) { tagService = INfcTag.Stub.asInterface(in.readStrongBinder()); } else { tagService = null; } return new Tag(id, techList, techExtras, serviceHandle, tagService); } @Override public Tag[] newArray(int size) { return new Tag[size]; } }; /** * For internal use only. * * @hide */ public synchronized void setConnectedTechnology(int technology) { if (mConnectedTechnology == -1) { mConnectedTechnology = technology; } else { throw new IllegalStateException("Close other technology first!"); } } /** * For internal use only. * * @hide */ public int getConnectedTechnology() { return mConnectedTechnology; } /** * For internal use only. * * @hide */ public void setTechnologyDisconnected() { mConnectedTechnology = -1; } }