drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* commit 'fba8b7f5963cb2bc15f06d83d986345978cc415e':
  docs: nfc ndef helper methods bug 5957772
This commit is contained in:
Robert Ly
2012-10-09 11:42:14 -07:00
committed by Android Git Automerger
parent 14dfe4e0ab fba8b7f596
commit 0f31450fe0
1 changed files with 63 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
docs/html/guide/topics/connectivity/nfc/nfc.jd
View File

@ -318,8 +318,8 @@ other two intents, giving the user a better experience.</p>
</pre> </pre>
</li> </li>
<li>The <code>uses-feature</code> element so that your application shows up in Google <li>The <code>uses-feature</code> element so that your application shows up in Google Play
Play only for devices that have NFC hardware: only for devices that have NFC hardware:
<pre> <pre>
&lt;uses-feature android:name="android.hardware.nfc" android:required="true" /&gt; &lt;uses-feature android:name="android.hardware.nfc" android:required="true" /&gt;
</pre> </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> <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 <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 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> record of the NDEF message that you are writing to a tag or beaming.</p>
<h3 id="abs-uri">TNF_ABSOLUTE_URI</h3> <h3 id="abs-uri">TNF_ABSOLUTE_URI</h3>
<p>Given the following {@link android.nfc.NdefRecord#TNF_ABSOLUTE_URI} NDEF record, which is <p class="note"><strong>Note:</strong> We recommend that you use the
stored as the first record inside of an {@link android.nfc.NdefMessage}:</p> <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> <pre>
NdefRecord uriRecord = new NdefRecord( NdefRecord uriRecord = new NdefRecord(
@ -526,7 +537,7 @@ NdefRecord uriRecord = new NdefRecord(
new byte[0], new byte[0]); new byte[0], new byte[0]);
</pre> </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> <pre>
&lt;intent-filter&gt; &lt;intent-filter&gt;
&lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt; &lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt;
@ -537,32 +548,35 @@ NdefRecord uriRecord = new NdefRecord(
&lt;/intent-filter&gt; &lt;/intent-filter&gt;
</pre> </pre>
<h3 id="mime">TNF_MIME_MEDIA</h3> <h3 id="mime">TNF_MIME_MEDIA</h3>
<p>Given the following {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record, which is stored as <p>You can create a {@link android.nfc.NdefRecord#TNF_MIME_MEDIA} NDEF record in the following ways.</p>
the first record inside
of an {@link android.nfc.NdefMessage}:</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> <pre>
NdefRecord mimeRecord = new NdefRecord( NdefRecord mimeRecord = new NdefRecord(
NdefRecord.TNF_MIME_MEDIA , 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"))); new byte[0], "Beam me up, Android!".getBytes(Charset.forName("US-ASCII")));
</pre> </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> <pre>
&lt;intent-filter&gt; &lt;intent-filter&gt;
&lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt; &lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt;
&lt;category android:name="android.intent.category.DEFAULT" /&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; &lt;/intent-filter&gt;
</pre> </pre>
<h3 id="well-known-text">TNF_WELL_KNOWN with RTD_TEXT</h3> <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 <p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following way:</p>
the first record inside of an {@link android.nfc.NdefMessage}:</p>
<pre> <pre>
public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) { public NdefRecord createTextRecord(String payload, Locale locale, boolean encodeInUtf8) {
byte[] langBytes = locale.getLanguage().getBytes(Charset.forName("US-ASCII")); 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> <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 <p>You can create a {@link android.nfc.NdefRecord#TNF_WELL_KNOWN} NDEF record in the following ways.</p>
the first record inside of an {@link android.nfc.NdefMessage}:</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> <pre>
byte[] uriField = "example.com".getBytes(Charset.forName("US-ASCII")); byte[] uriField = "example.com".getBytes(Charset.forName("US-ASCII"));
byte[] payload = new byte[uriField.length + 1]; //add 1 for the URI Prefix 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); NdefRecord.TNF_WELL_KNOWN, NdefRecord.RTD_URI, new byte[0], payload);
</pre> </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> <pre>
&lt;intent-filter&gt; &lt;intent-filter&gt;
@ -617,24 +642,32 @@ NdefRecord rtdUriRecord = new NdefRecord(
</pre> </pre>
<h3 id="ext-type">TNF_EXTERNAL_TYPE</h3> <h3 id="ext-type">TNF_EXTERNAL_TYPE</h3>
<p>Given the following {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record, which is stored <p>You can create a {@link android.nfc.NdefRecord#TNF_EXTERNAL_TYPE} NDEF record in the following ways:</p>
as the first record inside of an {@link android.nfc.NdefMessage}:</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> <pre>
byte[] payload; byte[] payload;
... ...
NdefRecord mimeRecord = new NdefRecord( NdefRecord extRecord = new NdefRecord(
NdefRecord.TNF_EXTERNAL_TYPE, "example.com:externalType", new byte[0], payload); NdefRecord.TNF_EXTERNAL_TYPE, "com.example:externalType", new byte[0], payload);
</pre> </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> <pre>
&lt;intent-filter&gt; &lt;intent-filter&gt;
&lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt; &lt;action android:name="android.nfc.action.NDEF_DISCOVERED" /&gt;
&lt;category android:name="android.intent.category.DEFAULT" /&gt; &lt;category android:name="android.intent.category.DEFAULT" /&gt;
&lt;data android:scheme="vnd.android.nfc" &lt;data android:scheme="vnd.android.nfc"
android:host="ext" android:host="ext"
android:pathPrefix="/example.com:externalType"/&gt; android:pathPrefix="/com.example:externalType"/&gt;
&lt;/intent-filter&gt; &lt;/intent-filter&gt;
</pre> </pre>
@ -840,8 +873,8 @@ public class Beam extends Activity implements CreateNdefMessageCallback {
String text = ("Beam me up, Android!\n\n" + String text = ("Beam me up, Android!\n\n" +
"Beam Time: " + System.currentTimeMillis()); "Beam Time: " + System.currentTimeMillis());
NdefMessage msg = new NdefMessage( NdefMessage msg = new NdefMessage(
new NdefRecord[] { createMimeRecord( new NdefRecord[] { createMime(
"application/com.example.android.beam", text.getBytes()) "application/vnd.com.example.android.beam", text.getBytes())
/** /**
* The Android Application Record (AAR) is commented out. When a device * 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 * 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 // record 0 contains the MIME type, record 1 is the AAR, if present
textView.setText(new String(msg.getRecords()[0].getPayload())); 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> </pre>
<p>Note that this code comments out an AAR, which you can remove. If you enable the AAR, the <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 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: filter is not technically necessary for Android 4.0 devices or later if the AAR is used:
</p> </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;intent-filter&gt;
&lt;action android:name="android.nfc.action.NDEF_DISCOVERED"/&gt; &lt;action android:name="android.nfc.action.NDEF_DISCOVERED"/&gt;
&lt;category android:name="android.intent.category.DEFAULT"/&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; &lt;/intent-filter&gt;
</pre> </pre>
<p>With this intent filter, the <code>com.example.android.beam</code> application now can be started <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 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 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 <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 recommended, because they let you start an Activity of your choice in your