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