Samsung Electronics logo

Samsung Web API: NFC

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API specifies a protocol for simple wireless interconnection of closely coupled devices operating at 13.56 MHz using Near Field Communication (NFC), which is an international standard (ISO/IEC 18092). To know more, see Technical Specifications.

There are three groups of application scenarios for NFC:

  • Exchanging some digital information or data by holding a device close to a wireless tag.
  • Exchanging some information or data between two devices by holding them close to each other.
  • Making payments by holding mobile phones close to point of sales terminals instead of swiping smart cards.

For more information on the NFC features, see NFC Guide.

Table of Contents

Summary of Interfaces and Methods

Interface Method
NFCManagerObject
NFCManager NFCAdapter getDefaultAdapter()
void setExclusiveMode(boolean mode)
NFCAdapter void setPowered(boolean state, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void setTagListener(NFCTagDetectCallback detectCallback, NFCTagType[]? tagFilter)
void setPeerListener(NFCPeerDetectCallback detectCallback)
void unsetTagListener()
void unsetPeerListener()
NDEFMessage? getCachedMessage()
NFCTag void readNDEF(NDEFMessageReadCallback readCallback, ErrorCallback? errorCallback)
void writeNDEF(NDEFMessage ndefMessage, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void transceive(byte[] data, ByteArraySuccessCallback dataCallback, ErrorCallback? errorCallback)
NFCPeer void setReceiveNDEFListener(NDEFMessageReadCallback successCallback)
void unsetReceiveNDEFListener()
void sendNDEF(NDEFMessage ndefMessage, SuccessCallback? successCallback, ErrorCallback? errorCallback)
NDEFMessage byte[] toByte()
NDEFRecord
NDEFRecordText
NDEFRecordURI
NDEFRecordMedia
NFCTagDetectCallback void onattach(NFCTag nfcTag)
void ondetach()
NFCPeerDetectCallback void onattach(NFCPeer nfcPeer)
void ondetach()
NDEFMessageReadCallback void onsuccess(NDEFMessage ndefMessage)
ByteArraySuccessCallback void onsuccess(byte[] data)

1. Type Definitions

1.1. NDEFRecordTextEncoding

An enumerator that defines an encoding format for an NDEF record text. 

  enum NDEFRecordTextEncoding { "UTF8", "UTF16" };

1.2. NFCTagType

An enumerator that defines the type of NFC tag. 

  enum NFCTagType { "GENERIC_TARGET", "ISO14443_A", "ISO14443_4A", "ISO14443_3A",
  "MIFARE_MINI", "MIFARE_1K", "MIFARE_4K", "MIFARE_ULTRA", "MIFARE_DESFIRE",
  "ISO14443_B", "ISO14443_4B", "ISO14443_BPRIME", "FELICA", "JEWEL", "ISO15693",
  "UNKNOWN_TARGET" };

The following values are supported:

  • GENERIC_TARGET
  • ISO14443_A
  • ISO14443_4A
  • ISO14443_3A
  • MIFARE_MINI
  • MIFARE_1K
  • MIFARE_4K
  • MIFARE_ULTRA
  • MIFARE_DESFIRE
  • ISO14443_B
  • ISO14443_4B
  • ISO14443_BPRIME
  • FELICA
  • JEWEL
  • ISO15693
  • UNKNOWN_TARGET

2. Interfaces

2.1. NFCManagerObject

This interface defines what is instantiated by the webapis object. 

  [NoInterfaceObject] interface NFCManagerObject {
    readonly attribute NFCManager nfc;
  };
  WebAPIs implements NFCManagerObject;

There will be a webapis.nfc object that allows access to the functionality of the NFC API.

2.2. NFCManager

Accesses to the NFC tag/target. 

  [NoInterfaceObject] interface NFCManager {

    const short NFC_RECORD_TNF_EMPTY = 0;

    const short NFC_RECORD_TNF_WELL_KNOWN = 1;

    const short NFC_RECORD_TNF_MIME_MEDIA = 2;

    const short NFC_RECORD_TNF_URI = 3;

    const short NFC_RECORD_TNF_EXTERNAL_RTD = 4;

    const short NFC_RECORD_TNF_UNKNOWN = 5;

    const short NFC_RECORD_TNF_UNCHANGED = 6;


    NFCAdapter getDefaultAdapter() raises(WebAPIException);


    void setExclusiveMode(boolean mode) raises(WebAPIException);
  };

It provides access to the API functionalities through the webapis.nfc interface.

CONSTANTS

short NFC_RECORD_TNF_EMPTY

A constant to indicate empty format of NDEF record's type field.

short NFC_RECORD_TNF_WELL_KNOWN

A constant to indicate Record Type Definition (RTD) format of NDEF record's type field.

short NFC_RECORD_TNF_MIME_MEDIA

A constant to indicate MIME media types format in RFC 2046 [RFC 2046] of NDEF record's type field.

short NFC_RECORD_TNF_URI

A constant to indicate absolute URI, as defined in RFC 3986 [RFC 3986] format in RFC 2046 [RFC 2046] of NDEF record's type field.

short NFC_RECORD_TNF_EXTERNAL_RTD

A constant to indicate NFC forum external type [NFC RTD] format in RFC 2046 [RFC 2046] of NDEF record's type field.

short NFC_RECORD_TNF_UNKNOWN

A constant to indicate unknown type format in RFC 2046 [RFC 2046] of NDEF record's type field.

short NFC_RECORD_TNF_UNCHANGED

A constant to indicate whether the payload is an intermediate or final chunk of a chunked NDEF record.

METHODS

getDefaultAdapter

Gets the default NFC adapter of the device.

Signature
NFCAdapter getDefaultAdapter();
Return value
NFCAdapter The default NFCAdapter object.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

Code example
 try {
  var adapter = webapis.nfc.getDefaultAdapter() ;
 } catch (err) {
  console.log (err.name +": " + err.message);
 }

setExclusiveMode

Gives priority to the current application for NFC operations over other applications when it is in the foreground.

Signature
void setExclusiveMode(boolean mode);

If the current application gets priority and it is in the foreground, the system stops sending application controls that are usually sent to pick an application to handle the request when detecting NFC Tag or receiving NDEF Message from the connected NFC peer-to-peer target.

But when the current application goes to the background, it loses the priority.

Parameters
  • mode
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: The value of exclusive mode.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

Code example
 try {
   webapis.nfc.setExclusiveMode(true) ;
 } catch (err) {
   console.log (err.name + ": " + err.message);
 }

2.3. NFCAdapter

This interface provides access to control the adapter by offering methods to control local NFC behaviors, such as turning on/off an adapter. 

  [NoInterfaceObject] interface NFCAdapter {

    readonly attribute boolean powered ;



    void setPowered(boolean state,
                    optional SuccessCallback? successCallback,
                    optional ErrorCallback? errorCallback) raises(WebAPIException);


    void setTagListener(NFCTagDetectCallback detectCallback,
                        optional NFCTagType[]? tagFilter) raises(WebAPIException);


    void setPeerListener(NFCPeerDetectCallback detectCallback) raises(WebAPIException);


    void unsetTagListener() raises(WebAPIException);


    void unsetPeerListener() raises(WebAPIException);


    NDEFMessage? getCachedMessage() raises(WebAPIException);

  };

ATTRIBUTES

readonly boolean powered

The state of the NFC adapter.

This attribute is read-only.

METHODS

setPowered

Sets the power of an NFC adapter to either a on state or a off state.

Signature
void setPowered(boolean state, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • ServiceNotAvailableError: If NFC device is busy.
  • UnknownError: In any other error occurs.
Parameters
  • state
    • Optional: No.
    • Nullable: No.
    • Type: boolean.
    • Description: The state of NFC adapter, true means on, false means off
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to call when NFC adapter is enabled or disabled successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var gNfcAdapter;
 var onPowerOn = function(){ // Called when NFC adapter is powered on
   try {
     console.log("Power on succeed");
     // Implement NFC communication routines ...
     gNfcAdapter.setPowered(
         false, // Disable NFC adapter
         function () {console.log("Power off succeed"); }, // Handle success
         function () {console.log("Power off failed"); }); // Handle failure
   } catch (err) {
     console.log (err.name + ": " + err.message);
   }
 };
 try {
   gNfcAdapter = webapis.nfc.getDefaultAdapter();
   if (!gNfcAdapter.powered) {
     gNfcAdapter.setPowered(
         true, // Enable NFC adapter
         onPowerOn,                                     // Handle succes
         function () {console.log("Power on failed")}); // Handle failure
   } else {
     onPowerOn();
   }
 } catch (err) {
   console.log (err.name + ": " + err.message);
 }

setTagListener

Registers a callback function to invoke when an NFC tag is detected.

Signature
void setTagListener(NFCTagDetectCallback detectCallback, optional NFCTagType[]? tagFilter);

If the registration completes successfully, the detectCallback must be invoked when NFC tag is detected.

If no tagFilter is passed, it shall consider the default tagFilter. that is to set all tag types.

Parameters
  • detectCallback
    • Optional: No.
    • Nullable: No.
    • Type: NFCTagDetectCallback.
    • Description: The method to invoke when a NFC tag is successfully detected.
  • tagFilter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: array.
    • Description: A filter to be used when specific NFC tag is detected.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type ServiceNotAvailableError, if the NFC service is not available.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var adapter = webapis.nfc.getDefaultAdapter();
 var onSuccessCB = {onattach : function(nfcTag) {
     console.log("NFC Tag's type is " + nfcTag.type);
   }, ondetach : function() {
     console.log("NFC Tag is detached");
   }};
 adapter.setTagListener(onSuccessCB);

setPeerListener

Registers a callback function to be invoked when NFC peer-to-peer target is detected.

Signature
void setPeerListener(NFCPeerDetectCallback detectCallback);

If the registration completes successfully, the detectCallback must be invoked when NFC peer-to-peer target is detected.

Parameters
  • detectCallback
    • Optional: No.
    • Nullable: No.
    • Type: NFCPeerDetectCallback.
    • Description: The method to invoke when a NFC peer-to-peer target is successfully detected.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type ServiceNotAvailableError, if the NFC service is not available.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var adapter = webapis.nfc.getDefaultAdapter();
 var onSuccessCB = {onattach : function(nfcPeer) {
     console.log("NFC Target is detected");
   }, ondetach : function() {
     console.log("NFC Target is detached");
   }};
 adapter.setPeerListener(onSuccessCB);

unsetTagListener

Unregisters the listener for detecting an NFC tag.

Signature
void unsetTagListener();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type ServiceNotAvailableError, if the NFC service is not available.

    with error type SecurityError, if this functionality is not allowed.

Code example
 var adapter = webapis.nfc.getDefaultAdapter();

 // Receives NFCTag
 var onSuccessCB = {onattach : function(nfcTag) {
     console.log("NFC Tag's type is " + nfcTag.type);
   }, ondetach : function() {
     console.log("NFC Tag is detached");
   }};

 // Unregister the listener
 function unsetListen() {
   adapter.unsetTagListener();
 }

 // Registers to be notified when NFC tag is detected.
 adapter.setTagListener(onSuccessCB)

unsetPeerListener

Unregisters the listener for detecting an NFC peer-to-peer target.

Signature
void unsetPeerListener();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type ServiceNotAvailableError, if the NFC service is not available.

    with error type SecurityError, if this functionality is not allowed.

Code example
 var adapter = webapis.nfc.getDefaultAdapter();

 // Receives an NFC peer.
 var onSuccessCB = {onattach : function(nfcPeer) {
     console.log("NFC Target is detected");
   }, ondetach : function() {
     console.log("NFC Target is detached");
   }};

 // Unregisters the listener.
 function unsetListen() {
   adapter.unsetPeerListener();
 }

 // Registers to be notified when NFC peer-to-peer target is detected.
 adapter.setPeerListener(onSuccessCB)

getCachedMessage

Gets the NDEF message cached when the tag is detected.

Signature
NDEFMessage? getCachedMessage();

If the operation completes successfully, the NDEF Message that was last read before launching your application should be returned.

Return value
NDEF Message that was last read before launching your application.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

Code example
 // Gets the cached message
 var cachedMessage = webapis.nfc.getDefaultAdapter().getCachedMessage();

2.4. NFCTag

This interface provides accesses to the NFC tag. 

  [NoInterfaceObject] interface NFCTag {

    readonly attribute NFCTagType type;


    readonly attribute boolean isSupportedNDEF;


    readonly attribute long ndefSize;


    readonly attribute object properties;


    readonly attribute boolean isConnected;



     void readNDEF(NDEFMessageReadCallback readCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);


    void writeNDEF(NDEFMessage ndefMessage,
                   optional SuccessCallback? successCallback,
                   optional ErrorCallback? errorCallback) raises(WebAPIException);


    void transceive(byte[] data,
                    ByteArraySuccessCallback dataCallback,
                    optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

ATTRIBUTES

readonly NFCTagType type

The type of the NFC tag.

This attribute is read-only.

readonly boolean isSupportedNDEF

An attribute to check if the NFC Tag supports NDEF format.

This attribute is read-only.

readonly long ndefSize

The size of NDEF message stored in the tag.

This attribute is read-only.

readonly object properties

The value is all tag information.

It is pairs of key and value. The array's index is the pair's key and value is its value.

This attribute is read-only.
Code example
 var adapter = webapis.nfc.getDefaultAdapter();
 var onSuccessCB = {onattach : function(nfcTag) {
     console.log("NFC Tag's type is " + nfcTag.type);
     for(var i in nfcTag.properties) {
       console.log("key:" + i + " value:" + nfcTag.properties[i]);
     }
   }, ondetach : function() {
     console.log("NFC Tag is detached");
   }};
 adapter.setTagListener(onSuccessCB);

readonly boolean isConnected

The value is necessary to check if this tag is connected.

This attribute is read-only.

METHODS

readNDEF

Reads the NDEF data from the NFC tag.

Signature
void readNDEF(NDEFMessageReadCallback readCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • ServiceNotAvailableError: If the NFC service is not available.
  • UnknownError: If any other error occurs.
Parameters
  • readCallback
    • Optional: No.
    • Nullable: No.
    • Type: NDEFMessageReadCallback.
    • Description: The method invoked in case of successfully reading the NDEF Data.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method invoked in case of any error during reading the NDEF Data.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported by platform or current Tag doesn't support NDEF format.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

writeNDEF

Writes the NDEF data to the NFC tag.

Signature
void writeNDEF(NDEFMessage ndefMessage, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • ServiceNotAvailableError: If the NFC service is not available.
  • UnknownError: In any other error case.
Parameters
  • ndefMessage
    • Optional: No.
    • Nullable: No.
    • Type: NDEFMessage.
    • Description: The NDEF message to write to NFC tag.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method invoked in case of successfully writing the NDEF Data.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method invoked in case of any error during writing the NDEF Data.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported by platform or current Tag doesn't support NDEF format.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

transceive

Access the raw format card. The transceive function is the only way to access the raw format card (not formatted). Each tag type requires its own command to access tags. This API provides low level access of tag operation. (Note that you must know each tag technology.)

Signature
void transceive(byte[] data, ByteArraySuccessCallback dataCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError : If any of the input parameters contain an invalid value.
  • ServiceNotAvailableError : If the NFC service is not available.
  • UnknownError : If any other error occurs.
Parameters
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The raw data to transceive with the NFC tag.
  • dataCallback
    • Optional: No.
    • Nullable: No.
    • Type: ByteArraySuccessCallback.
    • Description: Invoked in case of successfully transceiving the raw data.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Invoked in case of any error during transceiving the NDEF Data.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported by platform

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

2.5. NFCPeer

An interface that provides access to the NFC peer-to-peer target. 

  [NoInterfaceObject] interface NFCPeer {

    readonly attribute boolean isConnected;
    

    void setReceiveNDEFListener(NDEFMessageReadCallback successCallback) raises(WebAPIException);


    void unsetReceiveNDEFListener() raises(WebAPIException);


    void sendNDEF(NDEFMessage ndefMessage,
                  optional SuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);

  };

ATTRIBUTES

readonly boolean isConnected

The value is necessary to check if this NFC peer-to-peer target is connected.

This attribute is read-only.

METHODS

setReceiveNDEFListener

Registers a callback function to be invoked when an NDEF message is received from the connected NFC peer-to-peer target.

Signature
void setReceiveNDEFListener(NDEFMessageReadCallback successCallback);
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: NDEFMessageReadCallback.
    • Description: Invoked in case of successful receiving the message.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type ServiceNotAvailableError, if the NFC service is not available.

    with error type NotSupportedError, if the feature is not supported by platform

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 var adapter = webapis.nfc.getDefaultAdapter();

 // Receives NFCPeer
 var onSuccessCB = {onattach : function(nfcPeer) {
     console.log("NFC Target is detected");
     nfcPeer.setReceiveNDEFListener(
         function(message){
            console.log("Receive message");
         });
   }, ondetach : function() {
     console.log("NFC Target is detached");
   }};

 adapter.setPeerListener(onSuccessCB);

unsetReceiveNDEFListener

Unregisters the listener for receiving NDEF messages from the NFC peer-to-peer target connected.

Signature
void unsetReceiveNDEFListener();
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type ServiceNotAvailableError, if the NFC service is not available.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if the feature is not supported by platform

Code example
 var adapter = webapis.nfc.getDefaultAdapter();
 var onSuccessCB = {onattach : function(nfcPeer) {
     console.log("NFC Target is detected");
     nfcPeer.setReceiveNDEFListener(
         function(message){
            console.log("Receive message");
            nfcPeer.unsetReceiveNDEFListener();
         });
   }, ondetach : function() {
     console.log("NFC Target is detached");
   }};
 }

 adapter.setPeerListener(onSuccessCB);

sendNDEF

Sends data to the NFC peer-to-peer target.

Signature
void sendNDEF(NDEFMessage ndefMessage, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The ErrorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • ServiceNotAvailableError: If the NFC service is not available.
  • UnknownError: In any other error case.
Parameters
  • ndefMessage
    • Optional: No.
    • Nullable: No.
    • Type: NDEFMessage.
    • Description: The NDEF message to send to NFC peer-to-peer target.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: Invoked in case of successfully sending data to NFC peer-to-peer target.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Invoked in case of any error during sending.
Exceptions
  • WebAPIException:

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if the feature is not supported by platform

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

2.6. NDEFMessage

The NDEFMessage interface. 

  [Constructor(),
   Constructor(NDEFRecord[] ndefRecords),
   Constructor(byte[] rawData)]

  interface NDEFMessage {

    readonly attribute long recordCount;
    

    attribute NDEFRecord[] records;


    byte[] toByte() raises(WebAPIException);
  };

ATTRIBUTES

readonly long recordCount

The number of records in the NDEFMessage.

This attribute is read-only.

NDEFRecord[] records

The array of NDEFRecord objects in the NDEFMessage.

METHODS

toByte

Gets the serial byte array of the NDEF message.

Signature
byte[] toByte();

If the operation completes successfully, it returns the serial byte array of the NDEF message.

Return value
byte[] The raw data in the NDEFMessage.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type TypeMismatchError, if the records whose type is not NDEFRecord are included in the NDEFMessage.

    with error type SecurityError, if this functionality is not allowed.

    with error type NotSupportedError, if the feature is not supported by platform

Code example
 // Gets the cached message.
 var cachedMessage = webapis.nfc.getDefaultAdapter().getCachedMessage();
 var raw = cachedMessage.toByte();

2.7. NDEFRecord

The NDEFRecord interface. 

  [Constructor(short tnf, byte[] type, byte[] payload, optional byte[]? id),
   Constructor(byte[] raw_data)]

  interface NDEFRecord {

    readonly attribute short tnf;


    readonly attribute byte[] type;


    readonly attribute byte[] id;
    

    readonly attribute byte[] payload;
  };

ATTRIBUTES

readonly short tnf

The value of the record type (TNF value).

At least the following values must be supported:

  • NFC_RECORD_TNF_EMPTY - The record type is empty
  • NFC_RECORD_TNF_WELL_KNOWN - Record Type Definition (RTD) format [NFC RTD]
  • NFC_RECORD_TNF_MIME_MEDIA - MIME media types in RFC 2046 [RFC 2046]
  • NFC_RECORD_TNF_URI - Absolute URI as defined in RFC 3986 [RFC 3986]
  • NFC_RECORD_TNF_EXTERNAL_RTD - NFC forum external type [NFC RTD]
  • NFC_RECORD_TNF_UNKNOWN - The payload type is unknown
  • NFC_RECORD_TNF_UNCHANGED - It means the payload is an intermediate or final chunk of a chunked NDEF record
This attribute is read-only.

readonly byte[] type

The specified type in byte array.

The byte array contains 0 to 255 bytes.

This attribute is read-only.

readonly byte[] id

The record ID.

The byte array contains 0 to 255 bytes.

By default, this attribute is set to an empty array.

This attribute is read-only.

readonly byte[] payload

The record payload.

The byte array contains 0 to (2 ** 32 - 1) bytes.

This attribute is read-only.
Code example
 // Creates a new NDEF record.
 var newRecord = new webapis.NDEFRecordURI("http://www.samsungmobile.com/");
 var payload = newRecord.payload;

2.8. NDEFRecordText

The NDEFRecord that has the text type payload. 

  [Constructor(DOMString text, DOMString languageCode, optional DOMString? encoding)]

  interface NDEFRecordText : NDEFRecord {

    readonly attribute DOMString text;
    

    readonly attribute DOMString languageCode;
    

    readonly attribute NDEFRecordTextEncoding encoding;
  };

ATTRIBUTES

readonly DOMString text

The encoded text.

This attribute is read-only.

readonly DOMString languageCode

The language code string value, followed by IANA[RFC 3066] (for example, en-US, ko-KR).

This attribute is read-only.

readonly NDEFRecordTextEncoding encoding

The encoding type. By default, this attribute is set to UTF8.

This attribute is read-only.

2.9. NDEFRecordURI

The NDEFRecord that has URI type payload. 

  [Constructor(DOMString uri)]

  interface NDEFRecordURI : NDEFRecord {

    readonly attribute DOMString uri;
  };

ATTRIBUTES

readonly DOMString uri

The URI string that is stored in the payload.

This attribute is read-only.

2.10. NDEFRecordMedia

The NDEFRecord that has mime type payload. 

  [Constructor(DOMString mimeType, byte[] data)]

  interface NDEFRecordMedia : NDEFRecord {

    readonly attribute DOMString mimeType;
  };

ATTRIBUTES

readonly DOMString mimeType

The mime type [RFC 2046] (for example, text/plain, image/jpeg ).

This attribute is read-only.

2.11. NFCTagDetectCallback

The success callback to be invoked when an NFC tag is detected or lost. 

  [Callback, NoInterfaceObject] interface NFCTagDetectCallback {

    void onattach(NFCTag nfcTag);

    void ondetach();
  };

This callback interface specifies two methods:

  • onattach: invoked when an NFC tag is detected
  • ondetach: invoked when the NFC tag is lost

It is used in NFCAdapter.setTagListener().

METHODS

onattach

The method invoked when a tag is attached.

Signature
void onattach(NFCTag nfcTag);
Parameters
  • nfcTag
    • Optional: No.
    • Nullable: No.
    • Type: NFCTag.
    • Description: The attached NFC tag.

ondetach

The method invoked when the connected tag is detached.

Signature
void ondetach();

2.12. NFCPeerDetectCallback

The success callback to be invoked when an NFC peer-to-peer target is detected or lost. 

  [Callback, NoInterfaceObject] interface NFCPeerDetectCallback {

    void onattach(NFCPeer nfcPeer);

    void ondetach();
  };

This callback interface specifies two methods:

  • onattach: invoked when an NFC peer-to-peer target is detected
  • ondetach: invoked when the NFC peer-to-peer target is lost

It is used in NFCAdapter.setPeerListener().

METHODS

onattach

The method invoked when the NFC peer-to-peer target is attached.

Signature
void onattach(NFCPeer nfcPeer);
Parameters
  • nfcPeer
    • Optional: No.
    • Nullable: No.
    • Type: NFCPeer.
    • Description: The attached NFC peer-to-peer target.

ondetach

The method invoked when the NFC peer-to-peer target connected is detached.

Signature
void ondetach();

2.13. NDEFMessageReadCallback

The success callback to be invoked when data has been read successfully from the NFC tag or target. 

  [Callback=FunctionOnly, NoInterfaceObject] interface NDEFMessageReadCallback {

    void onsuccess(NDEFMessage ndefMessage);
  };

This callback interface specifies a success method with an NDEF message as an input parameter. It is used in asynchronous operations, such as NFCTag.readNDEF() or NFCPeer.setReceiveNDEFListener().

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(NDEFMessage ndefMessage);
Parameters
  • ndefMessage
    • Optional: No.
    • Nullable: No.
    • Type: NDEFMessage.
    • Description: NDEF message that is read from the NFC tag or target.

2.14. ByteArraySuccessCallback

The success callback to be invoked when NFCTag.transceive() completes successfully. 

  [Callback=FunctionOnly, NoInterfaceObject] interface ByteArraySuccessCallback {

    void onsuccess(byte[] data);
  };

This callback interface specifies a success method, with a raw data as an input parameter. It is used in NFCTag.transceive().

METHODS

onsuccess

The method invoked when the asynchronous call completes successfully.

Signature
void onsuccess(byte[] data);
Parameters
  • data
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The raw data that is read from NFC tag or response of transceive operation.

3. Full WebIDL 

module NFC {

  enum NDEFRecordTextEncoding { "UTF8", "UTF16" };


  enum NFCTagType { "GENERIC_TARGET", "ISO14443_A", "ISO14443_4A", "ISO14443_3A",
  "MIFARE_MINI", "MIFARE_1K", "MIFARE_4K", "MIFARE_ULTRA", "MIFARE_DESFIRE",
  "ISO14443_B", "ISO14443_4B", "ISO14443_BPRIME", "FELICA", "JEWEL", "ISO15693",
  "UNKNOWN_TARGET" };
  

  [NoInterfaceObject] interface NFCManagerObject {
    readonly attribute NFCManager nfc;
  };
  WebAPIs implements NFCManagerObject;


  [NoInterfaceObject] interface NFCManager {

    const short NFC_RECORD_TNF_EMPTY = 0;

    const short NFC_RECORD_TNF_WELL_KNOWN = 1;

    const short NFC_RECORD_TNF_MIME_MEDIA = 2;

    const short NFC_RECORD_TNF_URI = 3;

    const short NFC_RECORD_TNF_EXTERNAL_RTD = 4;

    const short NFC_RECORD_TNF_UNKNOWN = 5;

    const short NFC_RECORD_TNF_UNCHANGED = 6;


    NFCAdapter getDefaultAdapter() raises(WebAPIException);


    void setExclusiveMode(boolean mode) raises(WebAPIException);
  };



  [NoInterfaceObject] interface NFCAdapter {

    readonly attribute boolean powered ;



    void setPowered(boolean state,
                    optional SuccessCallback? successCallback,
                    optional ErrorCallback? errorCallback) raises(WebAPIException);


    void setTagListener(NFCTagDetectCallback detectCallback,
                        optional NFCTagType[]? tagFilter) raises(WebAPIException);


    void setPeerListener(NFCPeerDetectCallback detectCallback) raises(WebAPIException);


    void unsetTagListener() raises(WebAPIException);


    void unsetPeerListener() raises(WebAPIException);


    NDEFMessage? getCachedMessage() raises(WebAPIException);

  };



  [NoInterfaceObject] interface NFCTag {

    readonly attribute NFCTagType type;


    readonly attribute boolean isSupportedNDEF;


    readonly attribute long ndefSize;


    readonly attribute object properties;


    readonly attribute boolean isConnected;



     void readNDEF(NDEFMessageReadCallback readCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);


    void writeNDEF(NDEFMessage ndefMessage,
                   optional SuccessCallback? successCallback,
                   optional ErrorCallback? errorCallback) raises(WebAPIException);


    void transceive(byte[] data,
                    ByteArraySuccessCallback dataCallback,
                    optional ErrorCallback? errorCallback) raises(WebAPIException);
  };



  [NoInterfaceObject] interface NFCPeer {

    readonly attribute boolean isConnected;
    

    void setReceiveNDEFListener(NDEFMessageReadCallback successCallback) raises(WebAPIException);


    void unsetReceiveNDEFListener() raises(WebAPIException);


    void sendNDEF(NDEFMessage ndefMessage,
                  optional SuccessCallback? successCallback,
                  optional ErrorCallback? errorCallback) raises(WebAPIException);

  };

  [Constructor(),
   Constructor(NDEFRecord[] ndefRecords),
   Constructor(byte[] rawData)]

  interface NDEFMessage {

    readonly attribute long recordCount;
    

    attribute NDEFRecord[] records;


    byte[] toByte() raises(WebAPIException);
  };

  [Constructor(short tnf, byte[] type, byte[] payload, optional byte[]? id),
   Constructor(byte[] raw_data)]

  interface NDEFRecord {

    readonly attribute short tnf;


    readonly attribute byte[] type;


    readonly attribute byte[] id;
    

    readonly attribute byte[] payload;
  };

  [Constructor(DOMString text, DOMString languageCode, optional DOMString? encoding)]

  interface NDEFRecordText : NDEFRecord {

    readonly attribute DOMString text;
    

    readonly attribute DOMString languageCode;
    

    readonly attribute NDEFRecordTextEncoding encoding;
  };

  [Constructor(DOMString uri)]

  interface NDEFRecordURI : NDEFRecord {

    readonly attribute DOMString uri;
  };

  [Constructor(DOMString mimeType, byte[] data)]

  interface NDEFRecordMedia : NDEFRecord {

    readonly attribute DOMString mimeType;
  };

 

  [Callback, NoInterfaceObject] interface NFCTagDetectCallback {

    void onattach(NFCTag nfcTag);

    void ondetach();
  };


  [Callback, NoInterfaceObject] interface NFCPeerDetectCallback {

    void onattach(NFCPeer nfcPeer);

    void ondetach();
  };


  [Callback=FunctionOnly, NoInterfaceObject] interface NDEFMessageReadCallback {

    void onsuccess(NDEFMessage ndefMessage);
  };


  [Callback=FunctionOnly, NoInterfaceObject] interface ByteArraySuccessCallback {

    void onsuccess(byte[] data);
  };

};