• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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       * @throws SecurityException if the tag object is reused after the tag has left the field
180       */
connect()181      public void connect() throws IOException;
182  
183      /**
184       * Re-connect to the {@link Tag} associated with this connection. Reconnecting to a tag can be
185       * used to reset the state of the tag itself.
186       *
187       * <p>May cause RF activity and may block. Must not be called
188       * from the main application thread. A blocked call will be canceled with
189       * {@link IOException} by calling {@link #close} from another thread.
190       *
191       * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
192       *
193       * @see #connect()
194       * @see #close()
195       * @throws TagLostException if the tag leaves the field
196       * @throws IOException if there is an I/O failure, or connect is canceled
197       * @throws SecurityException if the tag object is reused after the tag has left the field
198       * @hide
199       */
reconnect()200      public void reconnect() throws IOException;
201  
202      /**
203       * Disable I/O operations to the tag from this {@link TagTechnology} object, and release resources.
204       * <p>Also causes all blocked I/O operations on other thread to be canceled and
205       * return with {@link IOException}.
206       *
207       * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
208       *
209       * @see #connect()
210       * @throws SecurityException if the tag object is reused after the tag has left the field
211       */
close()212      public void close() throws IOException;
213  
214      /**
215       * Helper to indicate if I/O operations should be possible.
216       *
217       * <p>Returns true if {@link #connect} has completed, and {@link #close} has not been
218       * called, and the {@link Tag} is not known to be out of range.
219       * <p>Does not cause RF activity, and does not block.
220       *
221       * @return true if I/O operations should be possible
222       */
isConnected()223      public boolean isConnected();
224  }
225