Merge "NFC documentation overhaul." into gingerbread (630ac8df) · Commits · e / os / android_frameworks_base

core/java/android/nfc/NfcAdapter.java

+48 −25

Original line number	Original line	Diff line number	Diff line
	@@ -33,10 +33,11 @@ import android.os.ServiceManager;
	import android.util.Log;		import android.util.Log;

	/**		/**
	* Represents the device's local NFC adapter.		* Represents the local NFC adapter.
	* <p>		* <p>
	* Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC		* Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC
	* adapter for this Android device.		* adapter for this Android device.
			* <p>
	*/		*/
	public final class NfcAdapter {		public final class NfcAdapter {
	private static final String TAG = "NFC";		private static final String TAG = "NFC";
	@@ -359,14 +360,13 @@ public final class NfcAdapter {

	/**		/**
	* Return true if this NFC Adapter has any features enabled.		* Return true if this NFC Adapter has any features enabled.
	* <p>
	* If this method returns false, then applications should request the user
	* turn on NFC tag discovery in Settings.
	* <p>
	* If this method returns false, the NFC hardware is guaranteed not to
	* perform or respond to any NFC communication.
	*		*
	* @return true if this NFC Adapter is enabled to discover new tags		* <p>Application may use this as a helper to suggest that the user
			* should turn on NFC in Settings.
			* <p>If this method returns false, the NFC hardware is guaranteed not to
			* generate or respond to any NFC transactions.
			*
			* @return true if this NFC Adapter has any features enabled
	*/		*/
	public boolean isEnabled() {		public boolean isEnabled() {
	try {		try {
	@@ -414,17 +414,24 @@ public final class NfcAdapter {
	}		}

	/**		/**
	* Enables foreground dispatching to the given Activity. This will force all NFC Intents that		* Enable foreground dispatch to the given Activity.
	* match the given filters to be delivered to the activity bypassing the standard dispatch		*
	* mechanism. If no IntentFilters are given all the PendingIntent will be invoked for every		* <p>This will give give priority to the foreground activity when
	* dispatch Intent.		* dispatching a discovered {@link Tag} to an application.
			*
			* <p>Activities must call {@link #disableForegroundDispatch} in
			* their {@link Activity#onPause} callback.
			*
			* <p>a null set of intent filters will cause the forground activity
			* to receive all tags.
	*		*
	* This method must be called from the main thread.		* <p>This method must be called from the main thread, and
			* only when the activity is in the foreground (resumed). *
	*		*
	* @param activity the Activity to dispatch to		* @param activity the Activity to dispatch to
	* @param intent the PendingIntent to start for the dispatch		* @param intent the PendingIntent to start for the dispatch
	* @param filters the IntentFilters to override dispatching for, or null to always dispatch		* @param filters the IntentFilters to override dispatching for, or null to always dispatch
	* @throws IllegalStateException		* @throws IllegalStateException if the Activity is not currently in the foreground
	*/		*/
	public void enableForegroundDispatch(Activity activity, PendingIntent intent,		public void enableForegroundDispatch(Activity activity, PendingIntent intent,
	IntentFilter[] filters, String[][] techLists) {		IntentFilter[] filters, String[][] techLists) {
	@@ -450,13 +457,16 @@ public final class NfcAdapter {
	}		}

	/**		/**
	* Disables foreground activity dispatching setup with		* Disable foreground dispatch to the given activity.
	* {@link #enableForegroundDispatch}.
	*		*
	* <p>This must be called before the Activity returns from		* <p>After calling {@link #enableForegroundDispatch}, an activity
	* it's <code>onPause()</code> or this method will throw an IllegalStateException.		* must call this method before its {@link Activity#onPause} callback
			* completes.
	*		*
	* <p>This method must be called from the main thread.		* <p>This method must be called from the main thread.
			*
			* @param activity the Activity to disable dispatch to
			* @throws IllegalStateException if the Activity has already been paused
	*/		*/
	public void disableForegroundDispatch(Activity activity) {		public void disableForegroundDispatch(Activity activity) {
	ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,		ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,
	@@ -484,13 +494,22 @@ public final class NfcAdapter {
	}		}

	/**		/**
	* Enable NDEF message push over P2P while this Activity is in the foreground. For this to		* Enable NDEF message push over P2P while this Activity is in the foreground.
	* function properly the other NFC device being scanned must support the "com.android.npp"		*
	* NDEF push protocol.		* <p>For this to function properly the other NFC device being scanned must
			* support the "com.android.npp" NDEF push protocol. Support for this
			* protocol is currently optional for Android NFC devices.
			*
			* <p>This method must be called from the main thread.
	*		*
	* <p><em>NOTE</em> While foreground NDEF push is active standard tag dispatch is disabled.		* <p><em>NOTE</em> While foreground NDEF push is active standard tag dispatch is disabled.
	* Only the foreground activity may receive tag discovered dispatches via		* Only the foreground activity may receive tag discovered dispatches via
	* {@link #enableForegroundDispatch}.		* {@link #enableForegroundDispatch}.
			*
			* @param activity the foreground Activity
			* @param msg a NDEF Message to push over P2P
			* @throws IllegalStateException if the Activity is not currently in the foreground
			* @throws OperationNotSupportedException if this Android device does not support NDEF push
	*/		*/
	public void enableForegroundNdefPush(Activity activity, NdefMessage msg) {		public void enableForegroundNdefPush(Activity activity, NdefMessage msg) {
	if (activity == null \|\| msg == null) {		if (activity == null \|\| msg == null) {
	@@ -510,13 +529,17 @@ public final class NfcAdapter {
	}		}

	/**		/**
	* Disables foreground NDEF push setup with		* Disable NDEF message push over P2P.
	* {@link #enableForegroundNdefPush}.
	*		*
	* <p>This must be called before the Activity returns from		* <p>After calling {@link #enableForegroundNdefPush}, an activity
	* it's <code>onPause()</code> or this method will throw an IllegalStateException.		* must call this method before its {@link Activity#onPause} callback
			* completes.
	*		*
	* <p>This method must be called from the main thread.		* <p>This method must be called from the main thread.
			*
			* @param activity the Foreground activity
			* @throws IllegalStateException if the Activity has already been paused
			* @throws OperationNotSupportedException if this Android device does not support NDEF push
	*/		*/
	public void disableForegroundNdefPush(Activity activity) {		public void disableForegroundNdefPush(Activity activity) {
	ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,		ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,

core/java/android/nfc/Tag.java

+86 −26

Original line number	Original line	Diff line number	Diff line
	@@ -16,6 +16,7 @@

	package android.nfc;		package android.nfc;

			import android.content.Context;
	import android.nfc.tech.IsoDep;		import android.nfc.tech.IsoDep;
	import android.nfc.tech.MifareClassic;		import android.nfc.tech.MifareClassic;
	import android.nfc.tech.MifareUltralight;		import android.nfc.tech.MifareUltralight;
	@@ -33,27 +34,69 @@ import android.os.Parcelable;
	import java.util.Arrays;		import java.util.Arrays;

	/**		/**
	* Represents a (generic) discovered tag.		* Represents an NFC tag that has been discovered.
	* <p>		* <p>
	* A tag is a passive NFC element, such as NFC Forum Tag's, MIFARE class Tags,		* {@link Tag} is an immutable object that represents the state of a NFC tag at
	* Sony FeliCa Tags, etc.		* the time of discovery. It can be used as a handle to {@link TagTechnology} classes
			* to perform advanced operations, or directly queried for its ID ({@link #getId} and the
			* set of technologies it contains ({@link #getTechList}). Arrays passed to and
			* returned by this class are not cloned, so be careful not to modify them.
	* <p>		* <p>
	* Tag's have a type and usually have a UID.		* A new tag object is created every time a tag is discovered (comes into range), even
			* if it is the same physical tag. If a tag is removed and then returned into range, then
			* only the most recent tag object can be successfully used to create a {@link TagTechnology}.
			*
			* <h3>Tag Dispatch</h3>
			* When a tag is discovered, a {@link Tag} object is created and passed to a
			* single application via the {@link NfcAdapter#EXTRA_TAG} extra in a
			* {@link Context#startActivity} {@link android.content.Intent}. A four stage dispatch is used to select the
			* most appropriate application to handle the tag. The Android OS executes each stage in order,
			* and completes dispatch as soon as a single matching application is found. If there are multiple
			* matching applications found at any one stage then the Android Activity Chooser dialog is shown
			* to allow the user to select the application.
			* <h4>1. Foreground activity dispatch</h4>
			* A foreground activity that has called {@link NfcAdapter#enableForegroundDispatch} is
			* given priority. See the documentation on {#link NfcAdapter#enableForegroundDispatch} for
			* its usage.
			* <h4>2. NDEF data dispatch</h4>
			* If the tag contains NDEF data, then {@link Context#startActivity} is called with
			* {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and a data URI determined from the
			* first NDEF Record in the first NDEF Message in the Tag. This allows NDEF tags to be given
			* priority dispatch to applications that can handle the content.
			* See {@link NfcAdapter#ACTION_NDEF_DISCOVERED} for more detail. If the tag does not contain
			* NDEF data, or if no application is registered
			* for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI then dispatch moves
			* to stage 3.
			* <h4>3. Tag Technology dispatch</h4>
			* {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_TECH_DISCOVERED} to
			* dispatch the tag to an application that can handle the technologies present on the tag.
			* Technologies are defined as sub-classes of {@link TagTechnology}, see the package
			* {@link android.nfc.tech}. The Android OS looks for an application that can handle one or
			* more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED for more detail.
			* <h4>4. Fall-back dispatch</h4>
			* If no application has been matched, then {@link Context#startActivity} is called with
			* {@link NfcAdapter#ACTION_TAG_DISCOVERED}. This is intended as a fall-back mechanism.
			* See {@link NfcAdapter#ACTION_TAG_DISCOVERED}.
			*
	* <p>		* <p>
	* {@link Tag} objects are passed to applications via the {@link NfcAdapter#EXTRA_TAG} extra		* <i>The Tag dispatch mechanism was designed to give a high probability of dispatching
	* in {@link NfcAdapter#ACTION_TAG_DISCOVERED} intents. A {@link Tag} object is immutable		* a tag to the correct application without showing the user an Application Chooser dialog.
	* and represents the state of the tag at the time of discovery. It can be		* This is important for NFC interactions because they are very transient - if a user has to
	* directly queried for its UID and Type, or used to create a {@link TagTechnology} using the		* move the Android device to choose an application then the connection is broken.</i>
	* static <code>get()</code> methods on the varios tech classes.		*
			* <h3>NFC Tag Background</h3>
			* An NFC tag is a passive NFC device, powered by the NFC field of this Android device while
			* it is in range. Tag's can come in many forms, such as stickers, cards, key fob, or
			* even embedded in a more sophisticated device.
			* <p>
			* Tags can have a wide range of capabilities. Simple tags just offer read/write semantics,
			* and contain some one time
			* programmable areas to make read-only. More complex tags offer math operations
			* and per-sector access control and authentication. The most sophisticated tags
			* contain operating environments such as Javacard, allowing complex interactions with the
			* applets executing on the tag. Use {@link TagTechnology} classes to access a broad
			* range of capabilities available in NFC tags.
	* <p>		* <p>
	* A {@link Tag} can be used to create a {@link TagTechnology} only while the tag is in
	* range. If it is removed and then returned to range, then the most recent
	* {@link Tag} object (in {@link NfcAdapter#ACTION_TAG_DISCOVERED}) should be used to create a
	* {@link TagTechnology}.
	* <p>This is an immutable data class. All properties are set at Tag discovery
	* 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.
	*/		*/
	public final class Tag implements Parcelable {		public final class Tag implements Parcelable {
	/package/ final byte[] mId;		/package/ final byte[] mId;
	@@ -149,21 +192,35 @@ public final class Tag implements Parcelable {

	/**		/**
	* Get the Tag Identifier (if it has one).		* Get the Tag Identifier (if it has one).
	* <p>Tag ID is usually a serial number for the tag.		* <p>The tag identifier is a low level serial number, used for anti-collision
	*		* and identification.
	* @return ID, or null if it does not exist		* <p> Most tags have a stable unique identifier
			* (UID), but some tags will generate a random ID every time they are discovered
			* (RID), and there are some tags with no ID at all (the byte array will be zero-sized).
			* <p> The size and format of an ID is specific to the RF technology used by the tag.
			* <p> This function retrieves the ID as determined at discovery time, and does not
			* perform any further RF communication or block.
			* @return ID as byte array, never null
	*/		*/
	public byte[] getId() {		public byte[] getId() {
	return mId;		return mId;
	}		}

	/**		/**
	* Returns technologies present in the tag that this implementation understands,		* Get the technologies available in this tag, as fully qualified class names.
	* or a zero length array if there are no supported technologies on this tag.		* <p>
	*		* A technology is an implementation of the {@link TagTechnology} interface,
	* The elements of the list are the names of the classes implementing the technology.		* and can be instantiated by calling the static <code>get(Tag)</code>
	*		* method on the implementation with this Tag. The {@link TagTechnology}
			* object can then be used to perform advanced, technology-specific operations on a tag.
			* <p>
			* Android defines a mandatory set of technologies that must be correctly
			* enumerated by all Android NFC devices, and an optional
			* set of proprietary technologies.
			* See {@link TagTechnology} for more details.
			* <p>
	* The ordering of the returned array is undefined and should not be relied upon.		* The ordering of the returned array is undefined and should not be relied upon.
			* @return an array of fully-qualified {@link TagTechnology} class-names.
	*/		*/
	public String[] getTechList() {		public String[] getTechList() {
	return mTechStringList;		return mTechStringList;
	@@ -198,6 +255,9 @@ public final class Tag implements Parcelable {
	return mTagService;		return mTagService;
	}		}

			/**
			* Human-readable description of the tag, for debugging.
			*/
	@Override		@Override
	public String toString() {		public String toString() {
	StringBuilder sb = new StringBuilder("TAG ")		StringBuilder sb = new StringBuilder("TAG ")

core/java/android/nfc/tech/IsoDep.java

+53 −32

Original line number	Original line	Diff line number	Diff line
	@@ -24,18 +24,14 @@ import android.util.Log;
	import java.io.IOException;		import java.io.IOException;

	/**		/**
	* A low-level connection to a {@link Tag} using the ISO-DEP technology, also known as		* Provides access to ISO-DEP (ISO 14443-4) properties and I/O operations on a {@link Tag}.
	* ISO1443-4.
	*		*
	* <p>You can acquire this kind of connection with {@link #get}.		* <p>Acquire a {@link IsoDep} object using {@link #get}.
	* Use this class to send and receive data with {@link #transceive transceive()}.		* <p>The primary ISO-DEP I/O operation is {@link #transceive}. Applications must
	*		* implement their own protocol stack on top of {@link #transceive}.
	* <p>Applications must implement their own protocol stack on top of		* <p>Tags that enumerate the {@link IsoDep} technology in {@link Tag#getTechList}
	* {@link #transceive transceive()}.		* will also enumerate
	*		* {@link NfcA} or {@link NfcB} (since IsoDep builds on top of either of these).
	* <p class="note"><strong>Note:</strong>
	* Use of this class requires the {@link android.Manifest.permission#NFC}
	* permission.
	*/		*/
	public final class IsoDep extends BasicTagTechnology {		public final class IsoDep extends BasicTagTechnology {
	private static final String TAG = "NFC";		private static final String TAG = "NFC";
	@@ -49,10 +45,13 @@ public final class IsoDep extends BasicTagTechnology {
	private byte[] mHistBytes = null;		private byte[] mHistBytes = null;

	/**		/**
	* Returns an instance of this tech for the given tag. If the tag doesn't support		* Get an instance of {@link IsoDep} for the given tag.
	* this tech type null is returned.		* <p>Does not cause any RF activity and does not block.
			* <p>Returns null if {@link IsoDep} was not enumerated in {@link Tag#getTechList}.
			* This indicates the tag does not support ISO-DEP.
	*		*
	* @param tag The tag to get the tech from		* @param tag an ISO-DEP compatible tag
			* @return ISO-DEP object
	*/		*/
	public static IsoDep get(Tag tag) {		public static IsoDep get(Tag tag) {
	if (!tag.hasTech(TagTechnology.ISO_DEP)) return null;		if (!tag.hasTech(TagTechnology.ISO_DEP)) return null;
	@@ -75,13 +74,13 @@ public final class IsoDep extends BasicTagTechnology {
	}		}

	/**		/**
	* Sets the timeout of an IsoDep transceive transaction in milliseconds.		* Set the timeout of {@link #transceive} in milliseconds.
	* If the transaction has not completed before the timeout,		* <p>The timeout only applies to ISO-DEP {@link #transceive}, and is
	* any ongoing {@link #transceive} operation will be		* reset to a default value when {@link #close} is called.
	* aborted and the connection to the tag is lost. This setting is applied		* <p>Setting a longer timeout may be useful when performing
	* only to the {@link Tag} object linked to this technology and will be		* transactions that require a long processing time on the tag
	* reset when {@link IsoDep#close} is called.		* such as key generation.
	* The default transaction timeout is 300 milliseconds.		* @param timeout timeout value in milliseconds
	*/		*/
	public void setTimeout(int timeout) {		public void setTimeout(int timeout) {
	try {		try {
	@@ -102,29 +101,51 @@ public final class IsoDep extends BasicTagTechnology {
	}		}

	/**		/**
	* Return the historical bytes if the tag is using {@link NfcA}, null otherwise.		* Return the ISO-DEP historical bytes for {@link NfcA} tags.
			* <p>Does not cause any RF activity and does not block.
			* <p>The historical bytes can be used to help identify a tag. They are present
			* only on {@link IsoDep} tags that are based on {@link NfcA} RF technology.
			* If this tag is not {@link NfcA} then null is returned.
			* <p>In ISO 14443-4 terminology, the historical bytes are a subset of the RATS
			* response.
			*
			* @return ISO-DEP historical bytes, or null if this is not a {@link NfcA} tag
	*/		*/
	public byte[] getHistoricalBytes() {		public byte[] getHistoricalBytes() {
	return mHistBytes;		return mHistBytes;
	}		}

	/**		/**
	* Return the hi layer response bytes if the tag is using {@link NfcB}, null otherwise.		* Return the higher layer response bytes for {@link NfcB} tags.
			* <p>Does not cause any RF activity and does not block.
			* <p>The higher layer response bytes can be used to help identify a tag.
			* They are present only on {@link IsoDep} tags that are based on {@link NfcB}
			* RF technology. If this tag is not {@link NfcB} then null is returned.
			* <p>In ISO 14443-4 terminology, the higher layer bytes are a subset of the
			* ATTRIB response.
			*
			* @return ISO-DEP historical bytes, or null if this is not a {@link NfcB} tag
	*/		*/
	public byte[] getHiLayerResponse() {		public byte[] getHiLayerResponse() {
	return mHiLayerResponse;		return mHiLayerResponse;
	}		}

	/**		/**
	* Send data to a tag and receive the response.		* Send raw ISO-DEP data to the tag and receive the response.
	* <p>		*
	* This method will block until the response is received. It can be canceled		* <p>Applications must only send the INF payload, and not the start of frame and
	* with {@link #close}.		* end of frame indicators. Applications do not need to fragment the payload, it
	* <p>Requires {@link android.Manifest.permission#NFC} permission.		* will be automatically fragmented and defragmented by {@link #transceive} if
			* it exceeds FSD/FSC limits.
			*
			* <p>This is an I/O operation and will block until complete. It must
			* not be called from the main application thread. A blocked call will be canceled with
			* {@link IOException} if {@link #close} is called from another thread.
	*		*
	* @param data bytes to send		* @param data command bytes to send, must not be null
	* @return bytes received in response		* @return response bytes received, will not be null
	* @throws IOException if the target is lost or connection closed		* @throws TagLostException if the tag leaves the field
			* @throws IOException if there is an I/O failure, or this operation is canceled
	*/		*/
	public byte[] transceive(byte[] data) throws IOException {		public byte[] transceive(byte[] data) throws IOException {
	return transceive(data, true);		return transceive(data, true);

core/java/android/nfc/tech/MifareClassic.java

+204 −62

File changed.

Preview size limit exceeded, changes collapsed.

core/java/android/nfc/tech/MifareUltralight.java

+72 −40

File changed.

Preview size limit exceeded, changes collapsed.