TagTechnology.java revision 74fe6c6b245ebe7d3b3d96962c32980d88dca4f5
1/* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.nfc.tech; 18 19import android.nfc.Tag; 20 21import java.io.Closeable; 22import java.io.IOException; 23 24/** 25 * {@link TagTechnology} is an interface to a technology in a {@link Tag}. 26 * <p> 27 * Obtain a {@link TagTechnology} implementation by calling the static method <code>get()</code> 28 * on the implementation class. 29 * <p> 30 * NFC tags are based on a number of independently developed technologies and offer a 31 * wide range of capabilities. The 32 * {@link TagTechnology} implementations provide access to these different 33 * technologies and capabilities. Some sub-classes map to technology 34 * specification (for example {@link NfcA}, {@link IsoDep}, others map to 35 * pseudo-technologies or capabilities (for example {@link Ndef}, {@link NdefFormatable}). 36 * <p> 37 * It is mandatory for all Android NFC devices to provide the following 38 * {@link TagTechnology} implementations. 39 * <ul> 40 * <li>{@link NfcA} (also known as ISO 14443-3A) 41 * <li>{@link NfcB} (also known as ISO 14443-3B) 42 * <li>{@link NfcF} (also known as JIS 6319-4) 43 * <li>{@link NfcV} (also known as ISO 15693) 44 * <li>{@link IsoDep} 45 * <li>{@link Ndef} on NFC Forum Type 1, Type 2, Type 3 or Type 4 compliant tags 46 * </ul> 47 * It is optional for Android NFC devices to provide the following 48 * {@link TagTechnology} implementations. If it is not provided, the 49 * Android device will never enumerate that class via {@link Tag#getTechList}. 50 * <ul> 51 * <li>{@link MifareClassic} 52 * <li>{@link MifareUltralight} 53 * <li>{@link NdefFormatable} must only be enumerated on tags for which this Android device 54 * is capable of formatting. Proprietary knowledge is often required to format a tag 55 * to make it NDEF compatible. 56 * </ul> 57 * <p> 58 * {@link TagTechnology} implementations provide methods that fall into two classes: 59 * <em>cached getters</em> and <em>I/O operations</em>. 60 * <h4>Cached getters</h4> 61 * These methods (usually prefixed by <code>get</code> or <code>is</code>) return 62 * properties of the tag, as determined at discovery time. These methods will never 63 * block or cause RF activity, and do not require {@link #connect} to have been called. 64 * They also never update, for example if a property is changed by an I/O operation with a tag 65 * then the cached getter will still return the result from tag discovery time. 66 * <h4>I/O operations</h4> 67 * I/O operations may require RF activity, and may block. They have the following semantics. 68 * <ul> 69 * <li>{@link #connect} must be called before using any other I/O operation. 70 * <li>{@link #close} must be called after completing I/O operations with a 71 * {@link TagTechnology}, and it will cancel all other blocked I/O operations on other threads 72 * (including {@link #connect} with {@link IOException}. 73 * <li>Only one {@link TagTechnology} can be connected at a time. Other calls to 74 * {@link #connect} will return {@link IOException}. 75 * <li>I/O operations may block, and should never be called on the main application 76 * thread. 77 * </ul> 78 */ 79public interface TagTechnology extends Closeable { 80 /** 81 * This technology is an instance of {@link NfcA}. 82 * <p>Support for this technology type is mandatory. 83 * @hide 84 */ 85 public static final int NFC_A = 1; 86 87 /** 88 * This technology is an instance of {@link NfcB}. 89 * <p>Support for this technology type is mandatory. 90 * @hide 91 */ 92 public static final int NFC_B = 2; 93 94 /** 95 * This technology is an instance of {@link IsoDep}. 96 * <p>Support for this technology type is mandatory. 97 * @hide 98 */ 99 public static final int ISO_DEP = 3; 100 101 /** 102 * This technology is an instance of {@link NfcF}. 103 * <p>Support for this technology type is mandatory. 104 * @hide 105 */ 106 public static final int NFC_F = 4; 107 108 /** 109 * This technology is an instance of {@link NfcV}. 110 * <p>Support for this technology type is mandatory. 111 * @hide 112 */ 113 public static final int NFC_V = 5; 114 115 /** 116 * This technology is an instance of {@link Ndef}. 117 * <p>Support for this technology type is mandatory. 118 * @hide 119 */ 120 public static final int NDEF = 6; 121 122 /** 123 * This technology is an instance of {@link NdefFormatable}. 124 * <p>Support for this technology type is mandatory. 125 * @hide 126 */ 127 public static final int NDEF_FORMATABLE = 7; 128 129 /** 130 * This technology is an instance of {@link MifareClassic}. 131 * <p>Support for this technology type is optional. If a stack doesn't support this technology 132 * type tags using it must still be discovered and present the lower level radio interface 133 * technologies in use. 134 * @hide 135 */ 136 public static final int MIFARE_CLASSIC = 8; 137 138 /** 139 * This technology is an instance of {@link MifareUltralight}. 140 * <p>Support for this technology type is optional. If a stack doesn't support this technology 141 * type tags using it must still be discovered and present the lower level radio interface 142 * technologies in use. 143 * @hide 144 */ 145 public static final int MIFARE_ULTRALIGHT = 9; 146 147 /** 148 * Get the {@link Tag} object backing this {@link TagTechnology} object. 149 * @return the {@link Tag} backing this {@link TagTechnology} object. 150 */ 151 public Tag getTag(); 152 153 /** 154 * Enable I/O operations to the tag from this {@link TagTechnology} object. 155 * <p>May cause RF activity and may block. Must not be called 156 * from the main application thread. A blocked call will be canceled with 157 * {@link IOException} by calling {@link #close} from another thread. 158 * <p>Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time. 159 * <p>Applications must call {@link #close} when I/O operations are complete. 160 * 161 * @see #close() 162 * @throws TagLostException if the tag leaves the field 163 * @throws IOException if there is an I/O failure, or connect is canceled 164 */ 165 public void connect() throws IOException; 166 167 /** 168 * Re-connect to the {@link Tag} associated with this connection. Reconnecting to a tag can be 169 * used to reset the state of the tag itself. 170 * 171 * <p>May cause RF activity and may block. Must not be called 172 * from the main application thread. A blocked call will be canceled with 173 * {@link IOException} by calling {@link #close} from another thread. 174 * 175 * @see #connect() 176 * @see #close() 177 * @throws TagLostException if the tag leaves the field 178 * @throws IOException if there is an I/O failure, or connect is canceled 179 * @hide 180 */ 181 public void reconnect() throws IOException; 182 183 /** 184 * Disable I/O operations to the tag from this {@link TagTechnology} object, and release resources. 185 * <p>Also causes all blocked I/O operations on other thread to be canceled and 186 * return with {@link IOException}. 187 * 188 * @see #connect() 189 */ 190 public void close() throws IOException; 191 192 /** 193 * Helper to indicate if I/O operations should be possible. 194 * 195 * <p>Returns true if {@link #connect} has completed, and {@link #close} has not been 196 * called, and the {@link Tag} is not known to be out of range. 197 * <p>Does not cause RF activity, and does not block. 198 * @return true if I/O operations should be possible 199 */ 200 public boolean isConnected(); 201} 202