|
|
| Line 87: |
Line 87: |
| '''nfc-share''' could be used to send large file (Blob) to another NFC peer. | | '''nfc-share''' could be used to send large file (Blob) to another NFC peer. |
| '''nfc-manager''' is used to control the RF state of NFC hardware. | | '''nfc-manager''' is used to control the RF state of NFC hardware. |
|
| |
| = NFC example =
| |
|
| |
| == NFC Utility function for parsing / constructing NDEF records==
| |
|
| |
| Gaia Application developers can use a helper library (<$GAIA_HOME>/shared/js/nfc_utils.js> to perform routine tasks such as parse incoming NDEF records or construct NDEF records.
| |
|
| |
| NfcUtils in {{bug|963556}} will provide some basic constants and utility functions to create and parse NDEF messages that follow NFCForum-TS-NDEF_1.0 specifications.
| |
|
| |
| The helper-utility exposes the following public functions:
| |
|
| |
| - parseNDEF : Parse a NDEF message
| |
| - parseHandoverNDEF : Parse a NDEF message that represents a handover request
| |
| or a handover select message
| |
| - searchForBluetoothAC : Search for a Bluetooth Alternate Carrier in a
| |
| handover NDEF message
| |
| - parseBluetoothSSP : Parses a Carrier Data Record that contains a
| |
| Bluetooth Secure Simple Pairing record
| |
| - encodeHandoverRequest: Returns a NDEF message that contains a handover
| |
| request message
| |
| - encodeHandoverSelect: Returns a NDEF message that contains a handover
| |
| select message
| |
|
| |
| ''Sample example to demonstrate the construction of an url as an NDEF Message:''
| |
| var tnf = NDEF.TNF_WELL_KNOWN;
| |
| var type = NDEF.RTD_URI;
| |
| var id = new Uint8Array();
| |
| // Short Record, 0x3 or "http://"
| |
| var payload = new Uint8Array(NfcUtils.fromUTF8('\u0003mozilla.org'));
| |
| var urlNDEFMsg = [new MozNDEFRecord(tnf, type, id, payload)];
| |
|
| |
| // Call writeNdef() API with urlNDEFMsg
| |
|
| |
| == NDEF Connect Example ==
| |
|
| |
| To establish an NFC application session, all NFCTag operations require an initial connect. It also selects the technology to use for subsequent operations until close/disconnect.
| |
|
| |
| nfctag = window.navigator.mozNfc.getNFCTag(sessionToken);
| |
|
| |
| var connectreq = nfctag.connect("NDEF");
| |
| connectreq.onsuccess = function() {
| |
| console.log('Connect success!');
| |
| };
| |
| connectreq.onerror = function() {
| |
| console.log('ERROR: Failed to connect.');
| |
| };
| |
|
| |
| == NFC Close Example ==
| |
|
| |
| Applications should close() the tag when done to release resources.
| |
|
| |
| var closereq = nfctag.close();
| |
| closereq.onsuccess = function() {
| |
| console.log('NFC tag close success!');
| |
| };
| |
| closereq.onerror = function() {
| |
| console.log('ERROR: Failed to close.');
| |
| };
| |
|
| |
| == NDEF Details Example ==
| |
|
| |
| var detailreq = nfctag.getDetailsNDEF();
| |
| detailreq.onsuccess = function() {
| |
| console.log('Max NDEF Message Length: ' + detailreq.result.maxNdefMsgLen);
| |
| };
| |
| detailreq.onerror = function() {
| |
| console.log('ERROR: Failed to get NDEF details.');
| |
| };
| |
|
| |
| == NDEF Read Example ==
| |
| The array of ndef records should be passed along in the web activity already read, but applications can still directly read the tag. The session token arrives from a MozActivity. NdefRecord fields are in Uint8Array format, they must first be unpacked in order to be read by applications.
| |
|
| |
| var conn = nfctag.connect("NDEF");
| |
| conn.onsuccess = function() {
| |
| var req = nfctag.readNDEF();
| |
| req.onsuccess = function() {
| |
| var records = req.result;
| |
| showRecords(records);
| |
| nfctag.close(); // This is a DOMRequest call, truncated code here.
| |
| };
| |
| req.onerror = function() {
| |
| nfctag.close(); // This is a DOMRequest call, truncated code here.
| |
| };
| |
| };
| |
|
| |
| function showRecords(records) {
| |
| records.forEach(function (record) {
| |
| console.log("Found a " + record.tnf + " record" +
| |
| " of type " + record.type +
| |
| " with ID " + record.id +
| |
| " and payload " + record.payload);
| |
| });
| |
| };
| |
|
| |
| == NDEF Write Tag Example ==
| |
|
| |
| var tnf = 1; // NFC Forum Well Known type
| |
| var type = new Uint8Array(NfcUtils.fromUTF8("U")); // URL type
| |
| var id = new Uint8Array(NfcUtils.fromUTF8("")); // id
| |
| var payload = new Uint8Array(NfcUtils.fromUTF8("\u0003mozilla.org")); // URL data, with a short record prefix 0x3 replacing http://
| |
|
| |
| var ndefRecords = [new MozNDEFRecord(tnf, type, id, payload)];
| |
|
| |
| var writereq = nfctag.writeNDEF(ndefRecords);
| |
| writereq.onsuccess = function(e) {
| |
| console.log("Successfully wrote records to tag");
| |
| };
| |
| writereq.onerror = function(e) {
| |
| console.log("Write failed!");
| |
| };
| |
|
| |
| == NDEF P2P Send Example ==
| |
| Peer to Peer communications to another NFC enabled device does not need a connect, as it will automatically connect implicitly. It also only supports NDEF, which is a common standard data format across different NFC devices.
| |
|
| |
| var tnf = 1; // NFC Forum Well Known type
| |
| var type = new Uint8Array(NfcUtils.fromUTF8("U")); // URL type
| |
| var id = new Uint8Array(NfcUtils.fromUTF8("")); // id
| |
| var payload = new Uint8Array(NfcUtils.fromUTF8("\u0003mozilla.org")); // URL data, with a short record prefix 0x3 replacing http://
| |
|
| |
| var ndefRecords = [new MozNDEFRecord(tnf, type, id, payload)];
| |
| var nfcdom = window.navigator.mozNfc;
| |
| nfcdom.onpeerready = function(event) {
| |
| var nfcPeer = nfcdom.getNFCPeer(event.detail); // 'event.detail' has sessionToken.
| |
| var req = nfcpeer.sendNDEF(ndefRecords); // push NDEF message to other NFC device.
| |
| req.onsuccess = function(e) {
| |
| console.log("Successfully pushed P2P message");
| |
| };
| |
| req.onerror = function(e) {
| |
| console.log("P2P push failed!");
| |
| };
| |
| };
| |
|
| |
| == NDEF P2P SendFile Example ==
| |
| During handover scenarios, in order to send a file
| |
| var nfcdom = window.navigator.mozNfc;
| |
| nfcdom.onpeerready = function(event) {
| |
| var nfcPeer = nfcdom.getNFCPeer(event.detail);
| |
| var blob = ... // construct a 'blob' that is of type 'file'.
| |
| // This 'blob' will be passed onto / handover to Bluetooth interface for the actual file transfer. (Wifi handover is not yet supported)
| |
| var req = nfcPeer.sendFile(blob);
| |
| req.onsuccess = function(e) {
| |
| console.log("Successfully sent file");
| |
| };
| |
| req.onerror = function(e) {
| |
| console.log("Send file failed!");
| |
| };
| |
| };
| |
|
| |
| In order to use this api, applications should have the nfc permission 'nfc-write'
| |
|
| |
| == Handover Support ==
| |
| '''Only Bluetooth Handover is supported currently'''
| |
|
| |
| Refer to this bug {{bug|903305}} for 'sendFile' api, and for implementation details, refer {{bug|933093}}.
| |
|
| |
|
| = Application Dispatch Order = | | = Application Dispatch Order = |