From 11b075e218b9921a953eeebe73fcd1a8a81f764b Mon Sep 17 00:00:00 2001 From: Nick Pelly Date: Thu, 28 Oct 2010 13:39:37 -0700 Subject: Hide some NFC API's. We are leaving enough API so that you can see when any Tag is discovered, get its ID, and get its NDEF messages. But for advanced use - creating tag connections and writing messages - we have 2 problems. Firstly a lot of the code is untested (RawTagConnection.transceive()), or in some cases known not to work (NdefTagConnection.write()). Secondly, there is still debate about how to best expose information about Tags. The set of data/methods exposed for a Tag changes completely depending on the tag technology. There may be multiple sets of technology implemented in a single tag. Tag A may have technology X and Y, Tag B may have technology Y and Z. Furthermore, some NFC controllers will be not be able to use all technologies, and so Android Device 1 may see technology X and Y on Tag A but Android device 2 may only see technology X. So we have a pretty challenging set of constraints to work under, and we are not convinced the current Tag and NdefTag class is the best approach going forwards. The Tag application should be able to remain unbundled, since it just needs to get incoming NDEF Messages. Change-Id: Ic09f094f33794e10f8d730fffe011c9a5957e0ac Signed-off-by: Nick Pelly --- api/current.xml | 632 +-------------------------- core/java/android/nfc/FormatException.java | 1 - core/java/android/nfc/NdefMessage.java | 8 +- core/java/android/nfc/NdefRecord.java | 2 +- core/java/android/nfc/NdefTag.java | 1 + core/java/android/nfc/NdefTagConnection.java | 1 + core/java/android/nfc/NfcAdapter.java | 36 +- core/java/android/nfc/RawTagConnection.java | 1 + core/java/android/nfc/Tag.java | 3 + core/java/android/nfc/package.html | 20 +- core/res/AndroidManifest.xml | 1 - 11 files changed, 46 insertions(+), 660 deletions(-) diff --git a/api/current.xml b/api/current.xml index d3d3e3d696d0..3056e47ebfb8 100644 --- a/api/current.xml +++ b/api/current.xml @@ -99791,7 +99791,7 @@ extends="java.lang.Object" abstract="false" static="false" - final="false" + final="true" deprecated="not deprecated" visibility="public" > @@ -99882,7 +99882,7 @@ extends="java.lang.Object" abstract="false" static="false" - final="false" + final="true" deprecated="not deprecated" visibility="public" > @@ -100162,173 +100162,26 @@ > - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - *

This is an immutable data class. */ -public class NdefMessage implements Parcelable { +public final class NdefMessage implements Parcelable { private static final byte FLAG_MB = (byte) 0x80; private static final byte FLAG_ME = (byte) 0x40; @@ -69,9 +69,9 @@ public class NdefMessage implements Parcelable { * Returns a byte array representation of this entire NDEF message. */ public byte[] toByteArray() { - //TODO(nxp): do not return null - //TODO(nxp): allocate the byte array once, copy each record once - //TODO(nxp): process MB and ME flags outside loop + //TODO: do not return null + //TODO: allocate the byte array once, copy each record once + //TODO: process MB and ME flags outside loop if ((mRecords == null) || (mRecords.length == 0)) return null; diff --git a/core/java/android/nfc/NdefRecord.java b/core/java/android/nfc/NdefRecord.java index 557e44da6f61..746d3df14633 100644 --- a/core/java/android/nfc/NdefRecord.java +++ b/core/java/android/nfc/NdefRecord.java @@ -35,7 +35,7 @@ import java.lang.UnsupportedOperationException; * large. *

This is an immutable data class. */ -public class NdefRecord implements Parcelable { +public final class NdefRecord implements Parcelable { /** * Indicates no type, id, or payload is associated with this NDEF Record. *

diff --git a/core/java/android/nfc/NdefTag.java b/core/java/android/nfc/NdefTag.java index 0626edb1c5ca..eb9d0dc92a04 100644 --- a/core/java/android/nfc/NdefTag.java +++ b/core/java/android/nfc/NdefTag.java @@ -35,6 +35,7 @@ import android.os.Parcelable; * time and calls on this class will retrieve those read-only properties, and * not cause any further RF activity or block. Note however that arrays passed to and * returned by this class are *not* cloned, so be careful not to modify them. + * @hide */ public class NdefTag extends Tag implements Parcelable { /** diff --git a/core/java/android/nfc/NdefTagConnection.java b/core/java/android/nfc/NdefTagConnection.java index 27fa25c01df0..aafdbfd94577 100644 --- a/core/java/android/nfc/NdefTagConnection.java +++ b/core/java/android/nfc/NdefTagConnection.java @@ -28,6 +28,7 @@ import android.util.Log; *

Note: * Use of this class requires the {@link android.Manifest.permission#NFC} * permission. + * @hide */ public class NdefTagConnection extends RawTagConnection { public static final int NDEF_MODE_READ_ONCE = 1; diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java index a093d121bcd8..cf80fafec08f 100644 --- a/core/java/android/nfc/NfcAdapter.java +++ b/core/java/android/nfc/NfcAdapter.java @@ -31,37 +31,29 @@ import android.util.Log; * Use the static {@link #getDefaultAdapter} method to get the default NFC * Adapter for this Android device. Most Android devices will have only one NFC * Adapter, and {@link #getDefaultAdapter} returns the singleton object. - *

- * {@link NfcAdapter} can be used to create {@link RawTagConnection} or - * {@link NdefTagConnection} connections to modify or perform low level access - * to NFC Tags. - *

- * Note: Some methods require the - * {@link android.Manifest.permission#NFC} permission. */ public final class NfcAdapter { /** - * Intent to start an activity when a non-NDEF tag is discovered. - * TODO(npelly) finalize decision on using CATEGORY or DATA URI to provide a - * hint for applications to filter the tag type. - * TODO(npelly) probably combine these two intents since tags aren't that simple + * Intent to start an activity when a tag is discovered. */ @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_TAG_DISCOVERED = "android.nfc.action.TAG_DISCOVERED"; /** - * Intent to start an activity when a NDEF tag is discovered. TODO(npelly) - * finalize decision on using CATEGORY or DATA URI to provide a hint for - * applications to filter the tag type. + * Mandatory Tag extra for the ACTION_TAG intents. + * @hide */ - @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) - public static final String ACTION_NDEF_TAG_DISCOVERED = - "android.nfc.action.NDEF_TAG_DISCOVERED"; + public static final String EXTRA_TAG = "android.nfc.extra.TAG"; /** - * Mandatory Tag extra for the ACTION_TAG and ACTION_NDEF_TAG intents. + * Optional NdefMessage[] extra for the ACTION_TAG intents. */ - public static final String EXTRA_TAG = "android.nfc.extra.TAG"; + public static final String EXTRA_NDEF_MESSAGES = "android.nfc.extra.NDEF_MESSAGES"; + + /** + * Optional byte[] extra for the tag identifier. + */ + public static final String EXTRA_ID = "android.nfc.extra.ID"; /** * Broadcast Action: a transaction with a secure element has been detected. @@ -324,6 +316,7 @@ public final class NfcAdapter { *

Requires {@link android.Manifest.permission#NFC} permission. * * @param message NDEF message to make public + * @hide */ public void setLocalNdefMessage(NdefMessage message) { try { @@ -338,6 +331,7 @@ public final class NfcAdapter { *

Requires {@link android.Manifest.permission#NFC} permission. * * @return NDEF Message that is publicly readable + * @hide */ public NdefMessage getLocalNdefMessage() { try { @@ -351,6 +345,7 @@ public final class NfcAdapter { /** * Create a raw tag connection to the default Target *

Requires {@link android.Manifest.permission#NFC} permission. + * @hide */ public RawTagConnection createRawTagConnection(Tag tag) { if (tag.mServiceHandle == 0) { @@ -367,6 +362,7 @@ public final class NfcAdapter { /** * Create a raw tag connection to the specified Target *

Requires {@link android.Manifest.permission#NFC} permission. + * @hide */ public RawTagConnection createRawTagConnection(Tag tag, String target) { if (tag.mServiceHandle == 0) { @@ -383,6 +379,7 @@ public final class NfcAdapter { /** * Create an NDEF tag connection to the default Target *

Requires {@link android.Manifest.permission#NFC} permission. + * @hide */ public NdefTagConnection createNdefTagConnection(NdefTag tag) { if (tag.mServiceHandle == 0) { @@ -399,6 +396,7 @@ public final class NfcAdapter { /** * Create an NDEF tag connection to the specified Target *

Requires {@link android.Manifest.permission#NFC} permission. + * @hide */ public NdefTagConnection createNdefTagConnection(NdefTag tag, String target) { if (tag.mServiceHandle == 0) { diff --git a/core/java/android/nfc/RawTagConnection.java b/core/java/android/nfc/RawTagConnection.java index 24072e5341a1..bfdaa77143a8 100644 --- a/core/java/android/nfc/RawTagConnection.java +++ b/core/java/android/nfc/RawTagConnection.java @@ -32,6 +32,7 @@ import android.util.Log; *

Note: * Use of this class requires the {@link android.Manifest.permission#NFC} * permission. + * @hide */ public class RawTagConnection { diff --git a/core/java/android/nfc/Tag.java b/core/java/android/nfc/Tag.java index dc6e798e189e..5d0b04cbccf3 100644 --- a/core/java/android/nfc/Tag.java +++ b/core/java/android/nfc/Tag.java @@ -41,6 +41,7 @@ import android.os.Parcelable; * time and calls on this class will retrieve those read-only properties, and * not cause any further RF activity or block. Note however that arrays passed to and * returned by this class are *not* cloned, so be careful not to modify them. + * @hide */ public class Tag implements Parcelable { /** @@ -156,6 +157,7 @@ public class Tag implements Parcelable { * from SENSF_RES * * @return poll bytes, or null if they do not exist for this Tag technology + * @hide */ public byte[] getPollBytes() { return mPollBytes; @@ -172,6 +174,7 @@ public class Tag implements Parcelable { *

JIS_X_6319_4: null *

ISO15693: response flags (1 byte), DSFID (1 byte): null * @return activation bytes, or null if they do not exist for this Tag technology + * @hide */ public byte[] getActivationBytes() { return mActivationBytes; diff --git a/core/java/android/nfc/package.html b/core/java/android/nfc/package.html index 8754cb9732c9..b054d1cc4179 100644 --- a/core/java/android/nfc/package.html +++ b/core/java/android/nfc/package.html @@ -1,30 +1,18 @@ -Provides access to Near Field Communication (NFC) functionality, allowing applications to connect -to NFC tags, then transmit and recieving data. A "tag" may actually be another device that appears -as a tag. +Provides access to Near Field Communication (NFC) functionality, allowing applications to read +NDEF message in NFC tags. A "tag" may actually be another device that appears as a tag.

Here's a summary of the classes:

{@link android.nfc.NfcAdapter}: This represents the device's NFC adapter, which is your entry-point to performing NFC -operations. Once you acquire an instance with {@link android.nfc.NfcAdapter#getDefaultAdapter}, you -can create connections to tags.
{@link android.nfc.NdefTag} and {@link android.nfc.Tag}: These objects represent a tag. A tag is a thing that the NFC-enabled device can -communicate with when within range. Usually, you'll work with {@link android.nfc.NdefTag}, which -represents a tag that's compliant with the NFC Data Exchange Format (NDEF); a {@link -android.nfc.Tag} represents a generalized tag. Note that {@link android.nfc.NdefTag} extends -{@link android.nfc.Tag}.
{@link android.nfc.NdefTagConnection} and {@link android.nfc.RawTagConnection}: These objects represent a connection to a tag, respective to the type of tag connected -(either {@link android.nfc.NdefTag} or {@link android.nfc.Tag}). Note that {@link -android.nfc.NdefTagConnection} extends {@link android.nfc.RawTagConnection}.
{@link android.nfc.NdefMessage}: Represents an NDEF data message, which is the standard format in which "records" carrying data are transmitted between devices and tags. Your application can receive these -messages from an {@link android.nfc.NdefTagConnection}.
{@link android.nfc.NdefRecord}: Represents a record, which is delivered in a {@link android.nfc.NdefMessage} and describes the type of data being shared and carries the data itself.