Merge "docs: nfc ndef helper methods bug 5957772" into jb-dev

1 files changed, 63 insertions, 40 deletions

diff --git a/docs/html/guide/topics/connectivity/nfc/nfc.jd b/docs/html/guide/topics/connectivity/nfc/nfc.jd
index 51c7bee..5011872 100644
--- a/docs/html/guide/topics/connectivity/nfc/nfc.jd
+++ b/docs/html/guide/topics/connectivity/nfc/nfc.jd
@@ -318,8 +318,8 @@ other two intents, giving the user a better experience.</p>
 </pre>
     </li>
 
-    <li>The <code>uses-feature</code> element so that your application shows up in Google
-Play only for devices that have NFC hardware:
+    <li>The <code>uses-feature</code> element so that your application shows up in Google Play
+    only for devices that have NFC hardware:
       <pre>
 &lt;uses-feature android:name="android.hardware.nfc" android:required="true" /&gt;
 </pre>
@@ -511,13 +511,24 @@ contain the payload and allow you to enumerate the tag's technologies:</p>
 
 <h2 id="creating-records">Creating Common Types of NDEF Records</h2>
 <p>This section describes how to create common types of NDEF records to help you when writing to
-NFC tags or sending data with Android Beam. It also describes how to create the corresponding
+NFC tags or sending data with Android Beam. Starting with Android 4.0 (API level 14), the
+{@link android.nfc.NdefRecord#createUri createUri()} method is available to help you create
+URI records automatically. Starting in Android 4.1 (API level 16), {@link android.nfc.NdefRecord#createExternal createExternal()}
+and {@link android.nfc.NdefRecord#createMime createMime()} are available to help you create
+MIME and external type NDEF records. Use these helper methods whenever possible to avoid mistakes
+when manually creating NDEF records.</p>
+
+<p>
+This section also describes how to create the corresponding
 intent filter for the record. All of these NDEF record examples should be in the first NDEF
 record of the NDEF message that you are writing to a tag or beaming.</p>
 
 <h3 id="abs-uri">TNF_ABSOLUTE_URI</h3>
-<p>Given the following {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI} NDEF record, which is
-stored as the first record inside of an {@link android.nfc.NdefMessage}:</p>
+<p class="note"><strong>Note:</strong> We recommend that you use the
+  <a href="#well-known-uri"><code>RTD_URI</code></a> type instead
+  of {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI}, because it is more efficient.</p>
+
+<p>You can create a {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI} NDEF record in the following way:</p>
 
 <pre>
 NdefRecord uriRecord = new NdefRecord(
@@ -526,7 +537,7 @@ NdefRecord uriRecord = new NdefRecord(
     new byte[0], new byte[0]);
 </pre>
 
-<p>the intent filter would look like this:</p>
+<p>The intent filter for the previous NDEF record would look like this:</p>
 <pre>
 &lt;intent-filter&gt;
     &lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt;
@@ -537,32 +548,35 @@ NdefRecord uriRecord = new NdefRecord(
 &lt;/intent-filter&gt;
 </pre>
 
-
 <h3 id="mime">TNF_MIME_MEDIA</h3>
-<p>Given the following {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record, which is stored as
-the first record inside
-of an {@link android.nfc.NdefMessage}:</p>
+<p>You can create a {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record in the following ways.</p>
+
+<p>Using the {@link android.nfc.NdefRecord#createMime createMime()} method:</p>
+<pre>
+NdefRecord mimeRecord = NdefRecord.createMime("application/vnd.com.example.android.beam",
+    "Beam me up, Android".getBytes(Charset.forName("US-ASCII")));
+</pre>
+
+<p>Creating the {@link android.nfc.NdefRecord} manually:</p>
 <pre>
 NdefRecord mimeRecord = new NdefRecord(
     NdefRecord.TNF_MIME_MEDIA ,
-    "application/com.example.android.beam".getBytes(Charset.forName("US-ASCII")),
+    "application/vnd.com.example.android.beam".getBytes(Charset.forName("US-ASCII")),
     new byte[0], "Beam me up, Android!".getBytes(Charset.forName("US-ASCII")));
 </pre>
 
-<p>the intent filter would look like this:</p>
+<p>The intent filter for the previous NDEF records would look like this:</p>
 <pre>
 &lt;intent-filter&gt;
     &lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt;
     &lt;category android:name="android.intent.category.DEFAULT" /&gt;
-    &lt;data android:mimeType="application/com.example.android.beam" /&gt;
+    &lt;data android:mimeType="application/vnd.com.example.android.beam" /&gt;
 &lt;/intent-filter&gt;
 </pre>
 
-
 <h3 id="well-known-text">TNF_WELL_KNOWN with RTD_TEXT</h3>
 
-<p>Given the following {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record, which is stored as
-the first record inside of an {@link android.nfc.NdefMessage}:</p>
+<p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following way:</p>
 <pre>
 public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) {
     byte[] langBytes = locale.getLanguage().getBytes(Charset.forName("US-ASCII"));
@@ -592,9 +606,20 @@ public NdefRecord createTextRecord(String payload, Locale locale, boolean encode
 
 <h3 id="well-known-uri">TNF_WELL_KNOWN with RTD_URI</h3>
 
-<p>Given the following {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record, which is stored as
-the first record inside of an {@link android.nfc.NdefMessage}:</p>
+<p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following ways.</p>
+
+<p>Using the {@link android.nfc.NdefRecord#createUri(String)} method:</p>
+<pre>
+NdefRecord rtdUriRecord1 = NdefRecord.createUri("http://example.com");
+</pre>
 
+<p>Using the {@link android.nfc.NdefRecord#createUri(Uri)} method:</p>
+<pre>
+Uri uri = new Uri("http://example.com");
+NdefRecord rtdUriRecord2 = NdefRecord.createUri(uri);
+</pre>
+
+<p>Creating the {@link android.nfc.NdefRecord} manually:</p>
 <pre>
 byte[] uriField = "example.com".getBytes(Charset.forName("US-ASCII"));
 byte[] payload = new byte[uriField.length + 1];              //add 1 for the URI Prefix
@@ -604,7 +629,7 @@ NdefRecord rtdUriRecord = new NdefRecord(
     NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, new byte[0], payload);
 </pre>
 
-<p>the intent filter would look like this:</p>
+<p>The intent filter for the previous NDEF records would look like this:</p>
 
 <pre>
 &lt;intent-filter&gt;
@@ -617,24 +642,32 @@ NdefRecord rtdUriRecord = new NdefRecord(
 </pre>
 
 <h3 id="ext-type">TNF_EXTERNAL_TYPE</h3>
-<p>Given the following {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record, which is stored
-as the first record inside of an {@link android.nfc.NdefMessage}:</p>
+<p>You can create a {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record in the following ways:</p>
+
+<p>Using the {@link android.nfc.NdefRecord#createExternal createExternal()} method:
+<pre>
+byte[] payload; //assign to your data
+String domain = "com.example"; //usually your app's package name
+String type = "externalType";
+NdefRecord extRecord = NdefRecord.createExternal(domain, type, payload);
+</pre>
 
+<p>Creating the {@link android.nfc.NdefRecord} manually:</p>
 <pre>
 byte[] payload;
 ...
-NdefRecord mimeRecord = new NdefRecord(
-    NdefRecord.TNF_EXTERNAL_TYPE, "example.com:externalType", new byte[0], payload);
+NdefRecord extRecord = new NdefRecord(
+    NdefRecord.TNF_EXTERNAL_TYPE, "com.example:externalType", new byte[0], payload);
 </pre>
 
-<p>the intent filter would look like this:</p>
+<p>The intent filter for the previous NDEF records would look like this:</p>
 <pre>
 &lt;intent-filter&gt;
     &lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt;
     &lt;category android:name="android.intent.category.DEFAULT" /&gt;
     &lt;data android:scheme="vnd.android.nfc"
         android:host="ext"
-        android:pathPrefix="/example.com:externalType"/&gt;
+        android:pathPrefix="/com.example:externalType"/&gt;
 &lt;/intent-filter&gt;
 </pre>
 
@@ -840,8 +873,8 @@ public class Beam extends Activity implements CreateNdefMessageCallback {
         String text = ("Beam me up, Android!\n\n" +
                 "Beam Time: " + System.currentTimeMillis());
         NdefMessage msg = new NdefMessage(
-                new NdefRecord[] { createMimeRecord(
-                        "application/com.example.android.beam", text.getBytes())
+                new NdefRecord[] { createMime(
+                        "application/vnd.com.example.android.beam", text.getBytes())
          /**
           * The Android Application Record (AAR) is commented out. When a device
           * receives a push with an AAR in it, the application specified in the AAR
@@ -882,22 +915,12 @@ public class Beam extends Activity implements CreateNdefMessageCallback {
         // record 0 contains the MIME type, record 1 is the AAR, if present
         textView.setText(new String(msg.getRecords()[0].getPayload()));
     }
-
-    /**
-     * Creates a custom MIME type encapsulated in an NDEF record
-     */
-    public NdefRecord createMimeRecord(String mimeType, byte[] payload) {
-        byte[] mimeBytes = mimeType.getBytes(Charset.forName("US-ASCII"));
-        NdefRecord mimeRecord = new NdefRecord(
-                NdefRecord.TNF_MIME_MEDIA, mimeBytes, new byte[0], payload);
-        return mimeRecord;
-    }
 }
 </pre>
 
 <p>Note that this code comments out an AAR, which you can remove. If you enable the AAR, the
 application specified in the AAR always receives the Android Beam message. If the application is not
-present, Google Play launches to download the application. Therefore, the following intent
+present, Google Play is started to download the application. Therefore, the following intent
 filter is not technically necessary for Android 4.0 devices or later if the AAR is used:
 </p>
 
@@ -905,13 +928,13 @@ filter is not technically necessary for Android 4.0 devices or later if the AAR
 &lt;intent-filter&gt;
   &lt;action android:name="android.nfc.action.NDEF_DISCOVERED"/&gt;
   &lt;category android:name="android.intent.category.DEFAULT"/&gt;
-  &lt;data android:mimeType="application/com.example.android.beam"/&gt;
+  &lt;data android:mimeType="application/vnd.com.example.android.beam"/&gt;
 &lt;/intent-filter&gt;
 </pre>
 <p>With this intent filter, the <code>com.example.android.beam</code> application now can be started
 when it scans an NFC tag or receives an Android Beam with an AAR of
 type <code>com.example.android.beam</code>, or when an NDEF formatted message contains a MIME record
-of type <code>application/com.example.android.beam</code>.</p>
+of type <code>application/vnd.com.example.android.beam</code>.</p>
 
 <p>Even though AARs guarantee an application is started or downloaded, intent filters are
 recommended, because they let you start an Activity of your choice in your