am 20856f71: am c9f7890a: Revise some javadocs for NFC; add package description

import android.os.Parcelable;

/**

 * NDEF Message data.

 * <p>

 * Immutable data class. An NDEF message always contains zero or more NDEF

 * records.

 * Represents an NDEF (NFC Data Exchange Format) data message that contains one or more {@link

 * NdefRecord}s.

 * <p>An NDEF message includes "records" that can contain different sets of data, such as

 * MIME-type media, a URI, or one of the supported RTD types (see {@link NdefRecord}). An NDEF

 * message always contains zero or more NDEF records.</p>

 * <p>This is an immutable data class.

 */

public class NdefMessage implements Parcelable {

    private static final byte FLAG_MB = (byte) 0x80;

import java.lang.UnsupportedOperationException;

/**

 * NDEF Record data.

 * <p>

 * Immutable data class. An NDEF record always contains

 * Represents a logical (unchunked) NDEF (NFC Data Exchange Format) record.

 * <p>An NDEF record always contains:

 * <ul>

 * <li>3-bit TNF field

 * <li>Variable length type

 * <li>Variable length ID

 * <li>Variable length payload

 * <li>3-bit TNF (Type Name Format) field: Indicates how to interpret the type field

 * <li>Variable length type: Describes the record format

 * <li>Variable length ID: A unique identifier for the record

 * <li>Variable length payload: The actual data payload

 * </ul>

 * The TNF (Type Name Format) field indicates how to interpret the type field.

 * <p>

 * This class represents a logical (unchunked) NDEF record. The underlying

 * <p>The underlying record

 * representation may be chunked across several NDEF records when the payload is

 * large.

 * <p>This is an immutable data class.

 */

public class NdefRecord implements Parcelable {

    /**

import android.os.Parcelable;

/**

 * NdefTag is a Tag that has NDEF messages or can store NDEF messages.

 * Represents a discovered tag that contains {@link NdefMessage}s (or a tag that can store them).

 * In practice, a tag is a thing that an NFC-enabled device can communicate with. This

 * class is a representation of such a tag and can contain the NDEF messages shared by the tag.

 * <p>An NDEF tag can contain zero or more NDEF messages (represented by {@link NdefMessage}

 * objects) in addition to the basic tag properties of UID and Type.

 * <p>

 * NDEF Tag's contain zero or more NDEF Messages in addition to the basic

 * Tag properties of UID and Type.

 * <p>

 * NDEF Tag's that have been initialized will usually contain a single NDEF

 * Message (and that Message can contain multiple NDEF Records). However it

 * is possible for NDEF Tag's to contain multiple NDEF Messages.

 * <p>

 * This class is a immutable data class that contains the contents of the NDEF

 * Message(s) as read at Tag discovery time.

 * <p>

 * NfcAdapter.createNdefTagConnection() can be used to modify the contents of

 * some NDEF Tag's.

 * {@link NdefTag}s that have been initialized will usually contain a single {@link NdefMessage}

 * (and that Message can contain multiple {@link NdefRecord}s). However it

 * is possible for {@link NdefTag}s to contain multiple {@link NdefMessage}s.

 * <p>{@link NfcAdapter#createNdefTagConnection createNdefTagConnection()} can be used to modify the

 * contents of some tags.

 * <p>This is an immutable data class.

 */

public class NdefTag extends Tag implements Parcelable {

    private final NdefMessage[] mMessages;

import android.util.Log;

/**

 * NdefTagConnection is a connection to an NDEF target on an NDEF tag.

 * A connection to an NDEF target on an {@link NdefTag}.

 * <p>You can acquire this kind of connection with {@link NfcAdapter#createNdefTagConnection

 * createNdefTagConnection()}. Use the connection to read or write {@link NdefMessage}s.

 */

public class NdefTagConnection extends RawTagConnection {

    public static final int NDEF_MODE_READ_ONCE = 1;

    /**

     * Read NDEF message(s).

     * This will always return the most up to date payload, and can block.

     * It can be canceled with close().

     * It can be canceled with {@link RawTagConnection#close}.

     * Most NDEF tags will contain just one NDEF message.

     * <p>

     * @throws FormatException if the tag is not NDEF formatted

    /**

     * Attempt to write an NDEF message to a tag.

     * This method will block until the data is written. It can be canceled

     * with close().

     * with {@link RawTagConnection#close}.

     * Many tags are write-once, so use this method carefully.

     * Specification allows for multiple NDEF messages per NDEF tag, but it is

     * encourage to only write one message, this so API only takes a single

     * message. Use NdefRecord to write several records to a single tag.

     * For write-many tags, use makeReadOnly() after this method to attempt

     * message. Use {@link NdefRecord} to write several records to a single tag.

     * For write-many tags, use {@link #makeReadOnly} after this method to attempt

     * to prevent further modification. For write-once tags this is not

     * neccesary.

     * Requires NFC_WRITE permission.

    /**

     * Attempts to make the NDEF data in this tag read-only.

     * This method will block until the action is complete. It can be canceled

     * with close().

     * with {@link RawTagConnection#close}.

     * Requires NFC_WRITE permission.

     * @return true if the tag is now read-only

     * @throws IOException if the target is lost, or connection closed

//TODO(npelly) permission {@link android.Manifest.permission#NFC_MODIFY}

/**

 * Represents a local NFC Adapter.

 * Represents the device's local NFC adapter.

 * <p>

 * Use the static {@link #getDefaultAdapter} method to get the default NFC

 * Adapter for this Android device. Most Android devices will have only one NFC