|
|
| (4 intermediate revisions by the same user not shown) |
| Line 58: |
Line 58: |
| * {{bug|979767}} | | * {{bug|979767}} |
|
| |
|
| == Fifth iteration: Secure Element (Firefox OS v2.2) == | | == Fifth iteration: Secure Element and NFC Privileged API (Firefox OS v2.2) == |
| * {{bug|1044428}} b2g-secure-element | | * {{bug|1044428}} b2g-secure-element |
| ** {{Bug|879861}} - NFC Secure Element Support | | ** {{Bug|879861}} - NFC Secure Element Support |
| ** {{Bug|1042851}} - (b2g-nfc-privilege) (meta) [NFC] Make NFC APIs available to privileged webapps
| | * {{Bug|1042851}} - (b2g-nfc-privilege) (meta) [NFC] Make NFC APIs available to privileged webapps |
| | ** Slide: http://bit.ly/1x7nWp5 |
|
| |
|
| = Current API = | | = Current API = |
| Line 79: |
Line 80: |
| = Application Permissions = | | = Application Permissions = |
|
| |
|
| NFC API can currently be used only by certified applications. | | NFC API has three permissions. |
| | * '''nfc''', which will be used by privileged applications. |
| | * '''nfc-share''', which will be used by ceritified(internal) applications. |
| | * '''nfc-manager', which will be used by System app. |
|
| |
|
| To use general reading NDEF API, at least '''nfc-read''' permission is required.
| | '''nfc''' permission could be used for general tag reading/writing, or sending NDEF to NFC Peer. |
| To write NDEF or to use NFCPeer, '''nfc-write''' is required.
| | '''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. |
| Application Usage Example:
| |
| | |
| "permissions": {
| |
| "nfc": { "access": "readwrite" }
| |
| }
| |
| | |
| '''** Only for internal user **'''
| |
| For those APIs used by the nfc_manager in System app, '''nfc-manager''' permission is required. It must '''not''' be used in any other application besides System App.
| |
| | |
| = 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 = |
| Dispatch priority is handled by the NFC Manager. In the numbered list below, a low number indicates higher priority. It generally dispatches according to the NFC technology type, and then the NDEF NDEF.TNF field, and the NDEF Record type field. If an activity is to be launched, it will display a activity list if there is more than one match.
| | 1) Foreground App, if the callback ontagfound/onpeerfound is set. |
| | | 2) If the foreground app doesn't register NFC callbacks or cannot process the event, the event will be redirected to System app, and System app will fire a nfc-ndef-discovered MozActivity. |
| 1) Foreground App, if the callback onforegrounddispatch is set. | |
| 2) P2P Handover Types (BT transfers, WiFi direct connection, etc.) | |
| 3) All other matches.
| |
| | |
| In #3, unknown tags are dispatched as a "nfc-tag-discovered" activity.
| |
|
| |
|
| = NFC on B2G emulator = | | = NFC on B2G emulator = |