android.nfc.tech.TagTechnology Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* 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}.
*
* Obtain a {@link TagTechnology} implementation by calling the static method get()
* on the implementation class.
*
* 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}).
*
* It is mandatory for all Android NFC devices to provide the following
* {@link TagTechnology} implementations.
*
* - {@link NfcA} (also known as ISO 14443-3A)
*
- {@link NfcB} (also known as ISO 14443-3B)
*
- {@link NfcF} (also known as JIS 6319-4)
*
- {@link NfcV} (also known as ISO 15693)
*
- {@link IsoDep}
*
- {@link Ndef} on NFC Forum Type 1, Type 2, Type 3 or Type 4 compliant tags
*
* 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}.
*
* - {@link MifareClassic}
*
- {@link MifareUltralight}
*
- {@link NfcBarcode}
*
- {@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.
*
*
* {@link TagTechnology} implementations provide methods that fall into two classes:
* cached getters and I/O operations.
*
Cached getters
* These methods (usually prefixed by get or is) 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.
* I/O operations
* I/O operations may require RF activity, and may block. They have the following semantics.
*
* - {@link #connect} must be called before using any other I/O operation.
*
- {@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}.
*
- Only one {@link TagTechnology} can be connected at a time. Other calls to
* {@link #connect} will return {@link IOException}.
*
- I/O operations may block, and should never be called on the main application
* thread.
*
*
* Note: 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}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int NFC_A = 1;
/**
* This technology is an instance of {@link NfcB}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int NFC_B = 2;
/**
* This technology is an instance of {@link IsoDep}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int ISO_DEP = 3;
/**
* This technology is an instance of {@link NfcF}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int NFC_F = 4;
/**
* This technology is an instance of {@link NfcV}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int NFC_V = 5;
/**
* This technology is an instance of {@link Ndef}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int NDEF = 6;
/**
* This technology is an instance of {@link NdefFormatable}.
*
Support for this technology type is mandatory.
* @hide
*/
public static final int NDEF_FORMATABLE = 7;
/**
* This technology is an instance of {@link MifareClassic}.
*
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}.
*
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}.
*
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;
/**
* 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.
*
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.
*
Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time.
*
Applications must call {@link #close} when I/O operations are complete.
*
*
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.
*
*
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.
*
*
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.
*
Also causes all blocked I/O operations on other thread to be canceled and
* return with {@link IOException}.
*
*
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.
*
*
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.
*
Does not cause RF activity, and does not block.
*
* @return true if I/O operations should be possible
*/
public boolean isConnected();
}