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 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 * 79 * <p class="note"><strong>Note:</strong> Methods that perform I/O operations 80 * require the {@link android.Manifest.permission#NFC} permission. 81 */ 82 public interface TagTechnology extends Closeable { 83 /** 84 * This technology is an instance of {@link NfcA}. 85 * <p>Support for this technology type is mandatory. 86 * @hide 87 */ 88 public static final int NFC_A = 1; 89 90 /** 91 * This technology is an instance of {@link NfcB}. 92 * <p>Support for this technology type is mandatory. 93 * @hide 94 */ 95 public static final int NFC_B = 2; 96 97 /** 98 * This technology is an instance of {@link IsoDep}. 99 * <p>Support for this technology type is mandatory. 100 * @hide 101 */ 102 public static final int ISO_DEP = 3; 103 104 /** 105 * This technology is an instance of {@link NfcF}. 106 * <p>Support for this technology type is mandatory. 107 * @hide 108 */ 109 public static final int NFC_F = 4; 110 111 /** 112 * This technology is an instance of {@link NfcV}. 113 * <p>Support for this technology type is mandatory. 114 * @hide 115 */ 116 public static final int NFC_V = 5; 117 118 /** 119 * This technology is an instance of {@link Ndef}. 120 * <p>Support for this technology type is mandatory. 121 * @hide 122 */ 123 public static final int NDEF = 6; 124 125 /** 126 * This technology is an instance of {@link NdefFormatable}. 127 * <p>Support for this technology type is mandatory. 128 * @hide 129 */ 130 public static final int NDEF_FORMATABLE = 7; 131 132 /** 133 * This technology is an instance of {@link MifareClassic}. 134 * <p>Support for this technology type is optional. If a stack doesn't support this technology 135 * type tags using it must still be discovered and present the lower level radio interface 136 * technologies in use. 137 * @hide 138 */ 139 public static final int MIFARE_CLASSIC = 8; 140 141 /** 142 * This technology is an instance of {@link MifareUltralight}. 143 * <p>Support for this technology type is optional. If a stack doesn't support this technology 144 * type tags using it must still be discovered and present the lower level radio interface 145 * technologies in use. 146 * @hide 147 */ 148 public static final int MIFARE_ULTRALIGHT = 9; 149 150 /** 151 * Get the {@link Tag} object backing this {@link TagTechnology} object. 152 * @return the {@link Tag} backing this {@link TagTechnology} object. 153 */ getTag()154 public Tag getTag(); 155 156 /** 157 * Enable I/O operations to the tag from this {@link TagTechnology} object. 158 * <p>May cause RF activity and may block. Must not be called 159 * from the main application thread. A blocked call will be canceled with 160 * {@link IOException} by calling {@link #close} from another thread. 161 * <p>Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time. 162 * <p>Applications must call {@link #close} when I/O operations are complete. 163 * 164 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 165 * 166 * @see #close() 167 * @throws TagLostException if the tag leaves the field 168 * @throws IOException if there is an I/O failure, or connect is canceled 169 */ connect()170 public void connect() throws IOException; 171 172 /** 173 * Re-connect to the {@link Tag} associated with this connection. Reconnecting to a tag can be 174 * used to reset the state of the tag itself. 175 * 176 * <p>May cause RF activity and may block. Must not be called 177 * from the main application thread. A blocked call will be canceled with 178 * {@link IOException} by calling {@link #close} from another thread. 179 * 180 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 181 * 182 * @see #connect() 183 * @see #close() 184 * @throws TagLostException if the tag leaves the field 185 * @throws IOException if there is an I/O failure, or connect is canceled 186 * @hide 187 */ reconnect()188 public void reconnect() throws IOException; 189 190 /** 191 * Disable I/O operations to the tag from this {@link TagTechnology} object, and release resources. 192 * <p>Also causes all blocked I/O operations on other thread to be canceled and 193 * return with {@link IOException}. 194 * 195 * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission. 196 * 197 * @see #connect() 198 */ close()199 public void close() throws IOException; 200 201 /** 202 * Helper to indicate if I/O operations should be possible. 203 * 204 * <p>Returns true if {@link #connect} has completed, and {@link #close} has not been 205 * called, and the {@link Tag} is not known to be out of range. 206 * <p>Does not cause RF activity, and does not block. 207 * 208 * @return true if I/O operations should be possible 209 */ isConnected()210 public boolean isConnected(); 211 } 212