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 17 package android.nfc.tech; 18 19 import android.nfc.Tag; 20 21 import java.io.Closeable; 22 import 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 NfcBarcode} 54 * <li>{@link NdefFormatable} must only be enumerated on tags for which this Android device 55 * is capable of formatting. Proprietary knowledge is often required to format a tag 56 * to make it NDEF compatible. 57 * </ul> 58 * <p> 59 * {@link TagTechnology} implementations provide methods that fall into two classes: 60 * <em>cached getters</em> and <em>I/O operations</em>. 61 * <h4>Cached getters</h4> 62 * These methods (usually prefixed by <code>get</code> or <code>is</code>) return 63 * properties of the tag, as determined at discovery time. These methods will never 64 * block or cause RF activity, and do not require {@link #connect} to have been called. 65 * They also never update, for example if a property is changed by an I/O operation with a tag 66 * then the cached getter will still return the result from tag discovery time. 67 * <h4>I/O operations</h4> 68 * I/O operations may require RF activity, and may block. They have the following semantics. 69 * <ul> 70 * <li>{@link #connect} must be called before using any other I/O operation. 71 * <li>{@link #close} must be called after completing I/O operations with a 72 * {@link TagTechnology}, and it will cancel all other blocked I/O operations on other threads 73 * (including {@link #connect} with {@link IOException}. 74 * <li>Only one {@link TagTechnology} can be connected at a time. Other calls to 75 * {@link #connect} will return {@link IOException}. 76 * <li>I/O operations may block, and should never be called on the main application 77 * thread. 78 * </ul> 79 * 80 * <p class="note"><strong>Note:</strong> Methods that perform I/O operations 81 * require the {@link android.Manifest.permission#NFC} permission. 82 */ 83 public interface TagTechnology extends Closeable { 84 /** 85 * This technology is an instance of {@link NfcA}. 86 * <p>Support for this technology type is mandatory. 87 * @hide 88 */ 89 public static final int NFC_A = 1; 90 91 /** 92 * This technology is an instance of {@link NfcB}. 93 * <p>Support for this technology type is mandatory. 94 * @hide 95 */ 96 public static final int NFC_B = 2; 97 98 /** 99 * This technology is an instance of {@link IsoDep}. 100 * <p>Support for this technology type is mandatory. 101 * @hide 102 */ 103 public static final int ISO_DEP = 3; 104 105 /** 106 * This technology is an instance of {@link NfcF}. 107 * <p>Support for this technology type is mandatory. 108 * @hide 109 */ 110 public static final int NFC_F = 4; 111 112 /** 113 * This technology is an instance of {@link NfcV}. 114 * <p>Support for this technology type is mandatory. 115 * @hide 116 */ 117 public static final int NFC_V = 5; 118 119 /** 120 * This technology is an instance of {@link Ndef}. 121 * <p>Support for this technology type is mandatory. 122 * @hide 123 */ 124 public static final int NDEF = 6; 125 126 /** 127 * This technology is an instance of {@link NdefFormatable}. 128 * <p>Support for this technology type is mandatory. 129 * @hide 130 */ 131 public static final int NDEF_FORMATABLE = 7; 132 133 /** 134 * This technology is an instance of {@link MifareClassic}. 135 * <p>Support for this technology type is optional. If a stack doesn't support this technology 136 * type tags using it must still be discovered and present the lower level radio interface 137 * technologies in use. 138 * @hide 139 */ 140 public static final int MIFARE_CLASSIC = 8; 141 142 /** 143 * This technology is an instance of {@link MifareUltralight}. 144 * <p>Support for this technology type is optional. If a stack doesn't support this technology 145 * type tags using it must still be discovered and present the lower level radio interface 146 * technologies in use. 147 * @hide 148 */ 149 public static final int MIFARE_ULTRALIGHT = 9; 150 151 /** 152 * This technology is an instance of {@link NfcBarcode}. 153 * <p>Support for this technology type is optional. If a stack doesn't support this technology 154 * type tags using it must still be discovered and present the lower level radio interface 155 * technologies in use. 156 * @hide 157 */ 158 public static final int NFC_BARCODE = 10; 159 160 /** 161 * Get the {@link Tag} object backing this {@link TagTechnology} object. 162 * @return the {@link Tag} backing this {@link TagTechnology} object. 163 */ getTag()164 public Tag getTag(); 165 166 /** 167 * Enable I/O operations to the tag from this {@link TagTechnology} object. 168 * <p>May cause RF activity and may block. Must not be called 169 * from the main application thread. A blocked call will be canceled with 170 * {@link IOException} by calling {@link #close} from another thread. 171 * <p>Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time. 172 * <p>Applications must call {@link #close} when I/O operations are complete. 173 * 174 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 175 * 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 */ connect()180 public void connect() throws IOException; 181 182 /** 183 * Re-connect to the {@link Tag} associated with this connection. Reconnecting to a tag can be 184 * used to reset the state of the tag itself. 185 * 186 * <p>May cause RF activity and may block. Must not be called 187 * from the main application thread. A blocked call will be canceled with 188 * {@link IOException} by calling {@link #close} from another thread. 189 * 190 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 191 * 192 * @see #connect() 193 * @see #close() 194 * @throws TagLostException if the tag leaves the field 195 * @throws IOException if there is an I/O failure, or connect is canceled 196 * @hide 197 */ reconnect()198 public void reconnect() throws IOException; 199 200 /** 201 * Disable I/O operations to the tag from this {@link TagTechnology} object, and release resources. 202 * <p>Also causes all blocked I/O operations on other thread to be canceled and 203 * return with {@link IOException}. 204 * 205 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 206 * 207 * @see #connect() 208 */ close()209 public void close() throws IOException; 210 211 /** 212 * Helper to indicate if I/O operations should be possible. 213 * 214 * <p>Returns true if {@link #connect} has completed, and {@link #close} has not been 215 * called, and the {@link Tag} is not known to be out of range. 216 * <p>Does not cause RF activity, and does not block. 217 * 218 * @return true if I/O operations should be possible 219 */ isConnected()220 public boolean isConnected(); 221 } 222