'''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 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 =
