NFC API
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.
Since: 1.0
Table of Contents
- 1. Type Definitions
- 1.1. NDEFRecordTextEncoding
- 1.2. NFCTagType
- 1.3. CardEmulationMode
- 1.4. SecureElementType
- 1.5. CardEmulationCategoryType
- 1.6. HCEEventType
- 1.7. AID
- 2. Interfaces
- 2.1. NFCManagerObject
- 2.2. NFCManager
- 2.3. NFCAdapter
- 2.4. NFCTag
- 2.5. NFCPeer
- 2.6. NDEFMessage
- 2.7. NDEFRecord
- 2.8. NDEFRecordText
- 2.9. NDEFRecordURI
- 2.10. NDEFRecordMedia
- 2.11. HCEEventData
- 2.12. AIDData
- 2.13. NFCTagDetectCallback
- 2.14. NFCPeerDetectCallback
- 2.15. NDEFMessageReadCallback
- 2.16. ByteArraySuccessCallback
- 2.17. CardEmulationModeChangeCallback
- 2.18. TransactionEventCallback
- 2.19. ActiveSecureElementChangeCallback
- 2.20. HCEEventReceiveCallback
- 2.21. AIDArraySuccessCallback
- 3. Related Feature
- 4. Full WebIDL
Summary of Interfaces and Methods
1. Type Definitions
1.1. NDEFRecordTextEncoding
enum NDEFRecordTextEncoding { "UTF8", "UTF16" };
Since: 1.0
- UTF8 - Corresponds to UTF8 NDEF record text encoding.
- UTF16 - Corresponds to UTF16 NDEF record text encoding.
1.2. NFCTagType
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" };
Since: 1.0
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
1.3. CardEmulationMode
enum CardEmulationMode { "ALWAYS_ON", "OFF" };
Since: 2.3
The following values are supported:
- ALWAYS_ON - Card emulation mode on
- OFF - Card emulation mode off
1.4. SecureElementType
enum SecureElementType { "ESE", "UICC", "HCE" };
Since: 2.3
The following values are supported:
- ESE - The eSE (Embedded Secure Element) secure element type
- UICC - The UICC (Universal Integrated Circuit Card) secure element type
- HCE - The HCE (Host Card Emulation) type. This allows a card to be emulated without secure element
Remark: HCE is supported since Tizen 2.3.1
1.5. CardEmulationCategoryType
enum CardEmulationCategoryType { "PAYMENT", "OTHER" };
Since: 2.3.1
The following values are supported:
- PAYMENT - Category used for NFC payment services
- OTHER - Category that can be used for all other cards
2. Interfaces
2.1. NFCManagerObject
[NoInterfaceObject] interface NFCManagerObject { readonly attribute NFCManager nfc; };
Tizen implements NFCManagerObject;
Since: 1.0
Attributes
-
readonly
NFCManager nfcObject representing a nfc manager.
Since: 1.0
2.2. NFCManager
[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); };
Since: 1.0
It provides access to the API functionalities through the tizen.nfc interface.
Constants
Since: 1.0
Since: 1.0
Since: 1.0
Since: 1.0
Since: 1.0
Since: 1.0
Since: 1.0
Methods
-
getDefaultAdapter
-
Gets the default NFC adapter of the device.
NFCAdapter getDefaultAdapter();
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.common
Return value:
-
NFCAdapter:
The default NFCAdapter object.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, in any other error case.
Code example:
try { var adapter = tizen.nfc.getDefaultAdapter(); } catch (err) { console.log(err.name + ": " + err.message); }
- WebAPIException
-
setExclusiveMode
-
Gives priority to the current application for NFC operations.
void setExclusiveMode(boolean mode);
Since: 2.1
If the current application has priority, and is in the foreground, the system will not generate application control requests to pick an application to handle NFC requests. Such a request is usually generated, for example, when detecting an NFC tag or receiving an NDEF message from a connected NFC peer-to-peer target.
When the current application moves to the background, it loses the priority.
The exclusive mode can only be set when NFC is on. If NFC is off, the mode is ignored.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.common
Parameters:
- mode: The value of the exclusive mode.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, in any other error case.
Code example:
try { tizen.nfc.setExclusiveMode(true); } catch (err) { console.log(err.name + ": " + err.message); }
2.3. NFCAdapter
[NoInterfaceObject] interface NFCAdapter { readonly attribute boolean powered; attribute CardEmulationMode cardEmulationMode raises(WebAPIException); attribute SecureElementType? activeSecureElement 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); long addCardEmulationModeChangeListener(CardEmulationModeChangeCallback changeCallback) raises(WebAPIException); void removeCardEmulationModeChangeListener(long watchId) raises(WebAPIException); long addTransactionEventListener(SecureElementType type, TransactionEventCallback eventCallback) raises(WebAPIException); void removeTransactionEventListener(long watchId) raises(WebAPIException); long addActiveSecureElementChangeListener(ActiveSecureElementChangeCallback changeCallback) raises(WebAPIException); void removeActiveSecureElementChangeListener(long watchId) raises(WebAPIException); NDEFMessage? getCachedMessage() raises(WebAPIException); void setExclusiveModeForTransaction(boolean mode) raises(WebAPIException); long addHCEEventListener(HCEEventReceiveCallback eventCallback) raises(WebAPIException); void removeHCEEventListener(long watchId) raises(WebAPIException); void sendHostAPDUResponse(byte[] apdu, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); boolean isActivatedHandlerForAID(SecureElementType type, AID aid) raises(WebAPIException); boolean isActivatedHandlerForCategory(SecureElementType type, CardEmulationCategoryType category) raises(WebAPIException); void registerAID(SecureElementType type, AID aid, CardEmulationCategoryType category) raises(WebAPIException); void unregisterAID(SecureElementType type, AID aid, CardEmulationCategoryType category) raises(WebAPIException); void getAIDsForCategory(SecureElementType type, CardEmulationCategoryType category, AIDArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setPreferredApp() raises(WebAPIException); void unsetPreferredApp() raises(WebAPIException); };
Since: 1.0
Attributes
-
readonly
boolean poweredThe state of the NFC adapter.
Since: 1.0
-
CardEmulationMode cardEmulationModeCard emulation mode of the NFC adapter.
To be allowed to change cardEmulationMode, the following privilege must be declared in the application's config.xml file.
- ALWAYS_ON - NFC card emulation feature is enabled. NFC card emulation related methods are available for use.
- OFF - NFC card emulation related methods cannot be used
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC card emulation is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation").
If it is not supported, NotSupportedError is thrown.
Security level can be determined by the manufacturer usage.
If a security issue is occurred, contact with the manufacturer of the product.
If you want to know about security level in detail, see the GSMA specification.Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege or a valid certificate to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type NotSupportedError, if NFC card emulation is not supported in a device.
with error type UnknownError, if any other error occurs.
-
SecureElementType activeSecureElement [nullable]Active secure element type.
To be allowed to change activeSecureElement, the following privilege must be declared in the application's config.xml file.
If the NFC service is not available, it returns null.
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC card emulation is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation").
If it is not supported, NotSupportedError is thrown.
Security level can be determined by the manufacturer usage.
If a security issue is occurred, contact with the manufacturer of the product.
If you want to know about security level in detail, see the GSMA specification.Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege or a valid certificate to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type NotSupportedError, if NFC card emulation is not supported in a device.
with error type UnknownError, if any other error occurs.
- WebAPIException
Methods
-
setTagListener
-
Registers a callback function to invoke when an NFC tag is detected.
void setTagListener(NFCTagDetectCallback detectCallback, optional NFCTagType[]? tagFilter);
Since: 1.0
If the registration completes successfully, detectCallback must be invoked when the NFC tag is detected.
If no tagFilter is passed, it shall consider the default tagFilter, that is to set all tag types.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.tag
Remark: http://tizen.org/feature/network.nfc.tag is added since Tizen 2.3.1. to check if NFC tag is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.tag").
Parameters:
- detectCallback: Callback method to be invoked when an NFC tag is successfully detected.
- tagFilter [optional] [nullable]: A filter to be used when a specific NFC tag is detected.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type NotSupportedError, if NFC tag is not supported.
with error type UnknownError, in any other error case.
Code example:
var adapter = tizen.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 an NFC peer-to-peer target is detected.
void setPeerListener(NFCPeerDetectCallback detectCallback);
Since: 1.0
If the registration completes successfully, the detectCallback must be invoked when an NFC peer-to-peer target is detected.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.p2p
Remark: http://tizen.org/feature/network.nfc.p2p is added since Tizen 2.3.1. to check if NFC p2p is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.p2p").
Parameters:
- detectCallback: Callback method to be invoked when an NFC peer-to-peer target is successfully detected.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type NotSupportedError, if NFC p2p is not supported.
with error type UnknownError, in any other error case.
Code example:
var adapter = tizen.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.
void unsetTagListener();
Since: 1.0
Calling this function has no effect if listener is not set.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.tag
Remark: http://tizen.org/feature/network.nfc.tag is added since Tizen 2.3.1. to check if NFC tag is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.tag").
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type NotSupportedError, if NFC tag is not supported.
with error type UnknownError, in any other error case.
Code example:
var adapter = tizen.nfc.getDefaultAdapter(); /* Receives NFCTag. */ var onSuccessCB = { onattach: function(nfcTag) { console.log("The attached NFC tag's type is " + nfcTag.type); }, ondetach: function() { console.log("NFC tag is detached"); /* Unregister the listener when the NFC tag is detached. */ adapter.unsetTagListener(); } }; /* Registers to be notified when NFC tag is detected. */ adapter.setTagListener(onSuccessCB);
- WebAPIException
-
unsetPeerListener
-
Unregisters the listener for detecting an NFC peer-to-peer target.
void unsetPeerListener();
Since: 1.0
Calling this function has no effect if listener is not set.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.p2p
Remark: http://tizen.org/feature/network.nfc.p2p is added since Tizen 2.3.1. to check if NFC p2p is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.p2p").
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type NotSupportedError, if NFC p2p is not supported.
with error type UnknownError, in any other error case.
Code example:
var adapter = tizen.nfc.getDefaultAdapter(); /* Receives an NFC peer. */ var onSuccessCB = { onattach: function(nfcPeer) { console.log("NFC peer target is attached"); }, ondetach: function() { console.log("NFC peer target is detached"); /* Unregisters the listener when NFC peer target is detached. */ adapter.unsetPeerListener(); } }; /* Registers to be notified when NFC peer target is detected. */ adapter.setPeerListener(onSuccessCB);
- WebAPIException
-
addCardEmulationModeChangeListener
-
Registers a callback function to invoke when the card emulation mode is changed.
long addCardEmulationModeChangeListener(CardEmulationModeChangeCallback changeCallback);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- changeCallback: Callback method to be invoked when the card emulation mode is changed.
Return value:
-
long:
Subscription identifier.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var onSuccessCB = function(mode) { console.log("The card emulation mode is " + mode); }; var listenerId = adapter.addCardEmulationModeChangeListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
removeCardEmulationModeChangeListener
-
Unsubscribes from receiving notification of card emulation mode changes.
void removeCardEmulationModeChangeListener(long watchId);
Since: 2.3
Calling this function has no effect if there is no listener with given id.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- watchId: Subscription identifier to remove.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { adapter.removeCardEmulationModeChangeListener(listenerId); } catch (err) { console.log(err.name + ": " + err.message); }
-
addTransactionEventListener
-
Registers a callback function to invoke when an external reader tries to access a secure element. Such an event may indicate initiating a financial transaction using the device.
long addTransactionEventListener(SecureElementType type, TransactionEventCallback eventCallback);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- type: Secure element type to listen.
- eventCallback: Callback method to be invoked when an external reader tries to access a secure element.
Return value:
-
long:
Subscription identifier.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var listenerId = adapter.addTransactionEventListener("UICC", function(aid, data) { console.log("Transaction event occurs"); }); } catch (err) { console.log(err.name + ": " + err.message); }
-
removeTransactionEventListener
-
Unsubscribes from receiving notification of transaction events.
void removeTransactionEventListener(long watchId);
Since: 2.3
Calling this function has no effect if there is no listener with given id.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- watchId: Subscription identifier to remove.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { adapter.removeTransactionEventListener(listenerId); } catch (err) { console.log(err.name + ": " + err.message); }
-
addActiveSecureElementChangeListener
-
Registers a callback function to invoke when an active secure element is changed.
long addActiveSecureElementChangeListener(ActiveSecureElementChangeCallback changeCallback);
Since: 2.3
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- changeCallback: Callback method to be invoked when an active secure element is changed.
Return value:
-
long:
Subscription identifier.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var onSuccessCB = function(seType) { console.log("Active secure element is " + seType); }; var listenerId = adapter.addActiveSecureElementChangeListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
removeActiveSecureElementChangeListener
-
Unsubscribes from receiving notification of active secure element changes.
void removeActiveSecureElementChangeListener(long watchId);
Since: 2.3
Calling this function has no effect if there is no listener with given id.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- watchId: Subscription identifier to remove.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { adapter.removeActiveSecureElementChangeListener(listenerId); } catch (err) { console.log(err.name + ": " + err.message); }
-
getCachedMessage
-
Gets the NDEF message cached when the tag is detected.
NDEFMessage? getCachedMessage();
Since: 1.0
If the operation completes successfully, the NDEF Message that is last read should be returned.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.common
Return value:
-
NDEFMessage [nullable]:
The NDEF Message that was last read.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, in any other error case.
Code example:
/* Gets the cached message. */ var cachedMessage = tizen.nfc.getDefaultAdapter().getCachedMessage();
- WebAPIException
-
setExclusiveModeForTransaction
-
Gives priority to the current application for NFC transaction events.
void setExclusiveModeForTransaction(boolean mode);
Since: 2.3
If the current application has priority, and is in the foreground, the system will not generate application control requests to pick an application to handle a transaction event request.
When the current application moves to the background, it loses priority.
An application is allowed to get priority only when it is in the foreground. Losing priority is always allowed regardless of an application's status.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: Security level can be determined by the manufacturer usage.
If a security issue is occurred, contact with the manufacturer of the product.
If you want to know about security level in detail, see the GSMA specification.Parameters:
- mode: Value of the exclusive mode.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method or a valid certificate to call this method.
with error type ServiceNotAvailableError, if the application is not in the foreground and is trying to get priority.
with error type NotSupportedError, if NFC card emulation is not supported.
with error type UnknownError, in any other error case.
Code example:
try { adapter.setExclusiveModeForTransaction(true); } catch (err) { console.log(err.name + ": " + err.message); }
-
addHCEEventListener
-
Registers a callback function for receiving HCE event.
long addHCEEventListener(HCEEventReceiveCallback eventCallback);
Since: 2.3.1
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- eventCallback: Callback method to be invoked when host device receives an APDU that is defined in the ISO/IEC 7816-4 specification.
Return value:
-
long:
Subscription identifier.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var onDetectedCB = function(event_data) { console.log("HCE event type is " + event_data.eventType); console.log("APDU is " + event_data.apdu); }; var listenerId = adapter.addHCEEventListener(onDetectedCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
removeHCEEventListener
-
Unsubscribes from receiving notification of a HCE event.
void removeHCEEventListener(long watchId);
Since: 2.3.1
Calling this function has no effect if there is no listener with given id.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Parameters:
- watchId: Subscription identifier to remove.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
with error type UnknownError, in any other error case.
Code example:
try { adapter.removeHCEEventListener(listenerId); } catch (err) { console.log(err.name + ": " + err.message); }
-
sendHostAPDUResponse
-
Sends host APDU response to CLF (Contactless Front-end).
void sendHostAPDUResponse(byte[] apdu, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.3.1
The ErrorCallback is launched with these error types:
- ServiceNotAvailableError - If the NFC service is not available.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- apdu: The APDU data to send. APDU is defined in the ISO/IEC 7816-4 specification.
- successCallback [optional] [nullable]: Invoked when an APDU is successfully sent to the NFC reader.
- errorCallback [optional] [nullable]: Invoked in case any error occurs while sending.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
Code example:
try { var successCB = function() { console.log("Sending APDU response was successful"); }; var errorCB = function() { console.log("Sending APDU response failed"); }; var classOfInstruction = 0x00; /* No SM or no SM indication. */ var instructionCode = 0xa4; /* Select File. */ var firstParam = 0x04; /* Direct selection by DF name. */ var secondParam = 0x00; /* First record. */ var dataFieldLength = 0x03; /* Variable length 1 or 3 bytes. */ var bytes = [0x20, 0x21, 0x22]; /* Variable length equal to dataFieldLength. */ var maxBytesExpected = 0x02; /* Maximum bytes in answer. */ var apdu_response = []; apdu_response = apdu_response.concat([classOfInstruction], [instructionCode], [firstParam], [secondParam], [dataFieldLength], bytes, [maxBytesExpected]); /* Sets apdu response. */ adapter.sendHostAPDUResponse(apdu_response, successCB, errorCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
isActivatedHandlerForAID
-
Allows an application to query whether an application is currently the activated handler for a specific AID and secure element type.
boolean isActivatedHandlerForAID(SecureElementType type, AID aid);
Since: 2.3.1
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- type: The secure element type.
- aid: Application ID, specified in ISO/IEC 7816-4.
Return value:
-
boolean:
true if current application is activated handler for the AID.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var aid = "ABC0012345"; var isActiveHandler = adapter.isActivatedHandlerForAID("HCE", aid); if (isActiveHandler) { console.log("Current application is activated handler for the AID"); } } catch (err) { console.log(err.name + ": " + err.message); }
-
isActivatedHandlerForCategory
-
Allows an application to query whether an application is currently the activated handler for a specific card emulation category and secure element type.
boolean isActivatedHandlerForCategory(SecureElementType type, CardEmulationCategoryType category);
Since: 2.3.1
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- type: The secure element type.
- category: The card emulation category type.
Return value:
-
boolean:
true if current application is activated handler for the category.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var isActiveHandler = adapter.isActivatedHandlerForCategory("ESE", "PAYMENT"); if (isActiveHandler) { console.log("Current application is activated handler for the category"); } } catch (err) { console.log(err.name + ": " + err.message); }
-
registerAID
-
Registers an AID for a specific category and secure element type.
void registerAID(SecureElementType type, AID aid, CardEmulationCategoryType category);
Since: 2.3.1
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- type: The secure element type.
- aid: Application Id, specified in ISO/IEC 7816-4.
- category: The card emulation category type.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var aid = "ABC0012345"; adapter.registerAID("HCE", aid, "PAYMENT"); } catch (err) { console.log(err.name + ": " + err.message); }
-
unregisterAID
-
Unregisters an AID that was previously registered for a specific card emulation category and secure element type. An application can only remove the AIDs which it registered.
void unregisterAID(SecureElementType type, AID aid, CardEmulationCategoryType category);
Since: 2.3.1
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- type: The secure element type.
- aid: Application Id, specified in ISO/IEC 7816-4.
- category: The card emulation category type.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
with error type UnknownError, in any other error case.
Code example:
try { var aid = "ABC0012345"; adapter.unregisterAID("HCE", aid, "PAYMENT"); } catch (err) { console.log(err.name + ": " + err.message); }
-
getAIDsForCategory
-
Retrieves AIDs that were previously registered for a specific card emulation category and secure element type. An application can only retrieve the AIDs which it registered.
void getAIDsForCategory(SecureElementType type, CardEmulationCategoryType category, AIDArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);
Since: 2.3.1
The ErrorCallback is launched with these error types:
- ServiceNotAvailableError - If the NFC service is not available.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC HCE is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation.hce").
If it is not supported, NotSupportedError is thrown.Parameters:
- type: The secure element type.
- category: The card emulation category type.
- successCallback: Invoked when the AIDs are retrieved successfully.
- errorCallback [optional] [nullable]: Invoked in case any error occurs while retrieving.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if NFC HCE feature is not supported.
Code example:
try { var successCB = function(aids) { var arrayLength = aids.length; for (var i = 0; i < arrayLength; i++) { console.log("Get AID category was successful"); console.log("AID type is " + aids[i].type); console.log("AID is " + aids[i].aid); console.log("AID isReadOnly is " + aids[i].readOnly); } }; var errorCB = function() { console.log("Get AID category failed"); }; adapter.getAIDsForCategory("HCE", "PAYMENT", successCB, errorCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
setPreferredApp
-
Sets current application as preferred application for NFC card emulation events as long as it is in foreground.
void setPreferredApp();
Since: 4.0
Calling the method allows to change routing priority of NFC card emulation without affecting NFC Settings (the Tap and pay option). As long as the application is in foreground, it will be set as the receiver of card emulation events instead of the application chosen in NFC Settings.
When the application leaves the foreground, receiving NFC card events is stopped for this application. The default application from settings will be used instead.
When the application comes back from background, receiving events is turned back on.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Warning: The application must follow the Using NFC Host-based Card Emulation to ensure proper behaviour. If the application does not respect above requirement, WebAPIException with error type AbortError will be thrown.
Remark: To check if NFC card emulation is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation").
Exceptions:
- WebAPIException
with error type AbortError, if any system error occurred.
with error type NotSupportedError, if this feature is not supported.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
Code example:
try { var adapter = tizen.nfc.getDefaultAdapter(); adapter.setPreferredApp(); } catch (err) { console.log(err.name + ": " + err.message); }
- WebAPIException
-
unsetPreferredApp
-
Unsets currently running application as preferred application for NFC card emulation events.
void unsetPreferredApp();
Since: 4.0
This method restores application chosen in NFC Settings (the Tap and pay option) as preferred for NFC card emulation events.
To set application as preferred again, use setPreferredApp().
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.cardemulation
Remark: To check if NFC card emulation is supported on this device, use tizen.systeminfo.getCapability("http://tizen.org/feature/network.nfc.card_emulation").
Exceptions:
- WebAPIException
with error type AbortError, if any system error occurred.
with error type NotSupportedError, if this feature is not supported.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
Code example:
try { var adapter = tizen.nfc.getDefaultAdapter(); adapter.setPreferredApp(); /* Perform some actions. */ adapter.unsetPreferredApp(); } catch (err) { console.log(err.name + ": " + err.message); }
- WebAPIException
2.4. NFCTag
[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); };
Since: 1.0
Attributes
-
readonly
NFCTagType typeThe type of the NFC tag.
Since: 1.0
-
readonly
boolean isSupportedNDEFAn attribute to check if the NFC Tag supports the NDEF format.
Since: 1.0
-
readonly
long ndefSizeThe size of an NDEF message stored in the tag.
Since: 1.0
-
readonly
object propertiesThe 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.
Since: 1.0
Code example:
var adapter = tizen.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 isConnectedThe value is necessary to check if this tag is connected.
Since: 1.0
Methods
-
readNDEF
-
Reads the NDEF data from the NFC tag.
void readNDEF(NDEFMessageReadCallback readCallback, optional ErrorCallback? errorCallback);
Since: 1.0
The ErrorCallback is launched with these error types:
- ServiceNotAvailableError - If the NFC service is not available.
- InvalidValuesError - If the current Tag doesn't support the NDEF standard.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.tag
Remark: If an NFC tag does not support the NDEF standard, InvalidValuesError would be returned instead of NotSupportedError since Tizen 2.3.
Parameters:
- readCallback: Callback method to be invoked in case reading the NDEF Data is completed successfully.
- errorCallback [optional] [nullable]: Callback method to be invoked in case any error occurs while reading the NDEF Data.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
try { var successCB = function(ndefMessage) { console.log("Message read was successful"); for (var i = 0; i < ndefMessage.recordCount; ++i) { console.log("Message record " + i + "tnf: " + ndefMessage.records[i].tnf); console.log("Message record " + i + "tnf: " + ndefMessage.records[i].tnf); console.log("Message record type " + ndefMessage.records[i].type.toString()); } }; var errorCB = function() { console.log("Message read failed"); }; nfcTag.readNDEF(successCB, errorCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
writeNDEF
-
Writes the NDEF data to the NFC tag.
void writeNDEF(NDEFMessage ndefMessage, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 1.0
The ErrorCallback is launched with these error types:
- InvalidValuesError: If any of the input parameters contain an invalid value or the current Tag does not support the NDEF standard.
- ServiceNotAvailableError: If the NFC service is not available.
- UnknownError: In any other error case.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.tag
Remark: If an NFC tag does not support the NDEF standard, InvalidValuesError would be returned instead of NotSupportedError since Tizen 2.3.
Parameters:
- ndefMessage: The NDEF message to write to an NFC tag.
- successCallback [optional] [nullable]: Callback method to be invoked in case writing the NDEF Data is completed successfully.
- errorCallback [optional] [nullable]: Callback method to be invoked in case any error occurs while writing the NDEF Data.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
try { var successCB = function() { console.log("Message write was successful"); }; var errorCB = function() { console.log("Message write failed"); }; var record = new tizen.NDEFRecordText("Hi!", "en-GB"); var message = new tizen.NDEFMessage([record]); nfcTag.writeNDEF(message, successCB, errorCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
transceive
-
Accesses 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 the tag operation. (Note that you must know each tag technology.)
void transceive(byte[] data, ByteArraySuccessCallback dataCallback, optional ErrorCallback? errorCallback);
Since: 1.0
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.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.tag
Parameters:
- data: The raw data to transceive with the NFC tag.
- dataCallback: Invoked in case transceiving the raw data is completed successfully.
- errorCallback [optional] [nullable]: Invoked in case any error occurs while transceiving the NDEF Data.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
try { var successCB = function(data) { console.log("Message write was successful"); console.log("Response is " + data.toString()); }; var errorCB = function() { console.log("Message write failed"); }; var message = [0x30, 0x00, 0x02, 0xa8]; /* READ command for MIFARE tags. */ nfcTag.transceive(message, successCB, errorCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.5. NFCPeer
[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); };
Since: 1.0
Attributes
-
readonly
boolean isConnectedThe value is necessary to check if this NFC peer-to-peer target is connected.
Since: 1.0
Methods
-
setReceiveNDEFListener
-
Registers a callback function to be invoked when an NDEF message is received from the connected NFC peer-to-peer target.
void setReceiveNDEFListener(NDEFMessageReadCallback successCallback);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.p2p
Parameters:
- successCallback: Invoked in case receiving the message is completed successfully.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type UnknownError, in any other error case.
Code example:
var adapter = tizen.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.
void unsetReceiveNDEFListener();
Since: 1.0
Calling this function has no effect if listener is not set.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.p2p
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type ServiceNotAvailableError, if the NFC service is not available.
with error type UnknownError, in any other error case.
Code example:
var adapter = tizen.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);
- WebAPIException
-
sendNDEF
-
Sends data to the NFC peer-to-peer target.
void sendNDEF(NDEFMessage ndefMessage, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 1.0
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.
Privilege level: public
Privilege: http://tizen.org/privilege/nfc.p2p
Parameters:
- ndefMessage: The NDEF message to send to the NFC peer-to-peer target.
- successCallback [optional] [nullable]: Invoked in case sending data to the NFC peer-to-peer target is completed successfully.
- errorCallback [optional] [nullable]: Invoked in case any error occurs while sending.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
try { peerListener = { onattach: function(peer) { var record = new tizen.NDEFRecordText("sendNDEF-test", "en-US"); var message = new tizen.NDEFMessage([record]); returned = peer.sendNDEF(ndefMessage); }, ondetach: function() { adapter.unsetPeerListener(); } }; adapter.setPeerListener(peerListener); } catch (err) { console.log(err.name + ": " + err.message); }
2.6. NDEFMessage
[Constructor(), Constructor(NDEFRecord[] ndefRecords), Constructor(byte[] rawData)] interface NDEFMessage { readonly attribute long recordCount; attribute NDEFRecord[] records; byte[] toByte() raises(WebAPIException); };
Since: 1.0
Code example:
try { var record = new tizen.NDEFRecordText("Hi!", "en-GB"); var tempMessage = new tizen.NDEFMessage([record]); var rawData = tempMessage.toByte(); var message = new tizen.NDEFMessage(rawData); } catch (err) { console.log(err.name + ": " + err.message); }
Constructors
-
Constructor ()
-
Constructor (NDEFRecord[])
-
Constructor (byte[])
NDEFMessage();
NDEFMessage(NDEFRecord[] ndefRecords);
NDEFMessage(byte[] rawData);
Attributes
-
readonly
long recordCountThe number of records in the NDEFMessage.
Since: 1.0
-
NDEFRecord[]
recordsThe array of NDEFRecord objects in the NDEFMessage.
Since: 1.0
Code example:
try { /* Prepares two NDEFRecords. */ var myRecordURI = new tizen.NDEFRecordURI("https://www.tizen.org/"); var myRecordTextPlain = new tizen.NDEFRecordMedia("text/plain", [116, 105, 122, 101, 110]); /* Creates a NDEFMessage composed of two NDEFRecords. */ var myMessage = new NDEFMessage([myRecordURI, myRecordTextPlain]); } catch (err) { console.log(err.name + ": " + err.message); }
Methods
-
toByte
-
Gets the serial byte array of the NDEF message.
byte[] toByte();
Since: 1.0
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 TypeMismatchError, if the records whose type is not NDEFRecord are included in the NDEFMessage.
with error type UnknownError, in any other error case.
Code example:
/* Gets the cached message. */ var cachedMessage = tizen.nfc.getDefaultAdapter().getCachedMessage(); var raw = cachedMessage.toByte();
- WebAPIException
2.7. NDEFRecord
[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; };
Since: 1.0
Code example:
try { var recordBytes = [217, 1, 2, 3, 202, 219, 218, 217, 240, 241]; var record = new tizen.NDEFRecord(recordBytes); } catch (err) { console.log(err.name + ": " + err.message); }
Code example:
try { var type = new Array(255); var payload = new Array(256); var recordId = [155, 150]; var newRecord = new tizen.NDEFRecord(tizen.nfc.NFC_RECORD_TNF_UNKNOWN, type, payload, recordId); } catch (err) { console.log(err.name + ": " + err.message); }
Constructors
Attributes
-
readonly
short tnfThe 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
Since: 1.0
-
readonly
byte[]
typeThe specified type in byte array.
The byte array contains 0 to 255 bytes.
Since: 1.0
-
readonly
byte[]
idThe record ID.
The byte array contains 0 to 255 bytes.
By default, this attribute is set to an empty array.
Since: 1.0
-
readonly
byte[]
payloadThe record payload.
The byte array contains 0 to (2 ** 32 - 1) bytes.
Since: 1.0
Code example:
/* Creates a new NDEF record. */ var newRecord = new tizen.NDEFRecordURI("https://www.tizen.org/"); var payload = newRecord.payload;
2.8. NDEFRecordText
[Constructor(DOMString text, DOMString languageCode, optional DOMString? encoding)] interface NDEFRecordText : NDEFRecord { readonly attribute DOMString text; readonly attribute DOMString languageCode; readonly attribute NDEFRecordTextEncoding encoding; };
Since: 1.0
Constructors
Attributes
-
readonly
DOMString textThe encoded text.
Since: 1.0
-
readonly
DOMString languageCodeThe language code string value, followed by IANA[RFC 3066] (for example, en-US, ko-KR).
Since: 1.0
-
readonly
NDEFRecordTextEncoding encodingThe encoding type. By default, this attribute is set to UTF8.
Since: 1.0
Code example:
var newRecord = new tizen.NDEFRecordText("Tizen", "en-US", "UTF8");
2.9. NDEFRecordURI
[Constructor(DOMString uri)] interface NDEFRecordURI : NDEFRecord { readonly attribute DOMString uri; };
Since: 1.0
Attributes
-
readonly
DOMString uriThe URI string that is stored in the payload.
Since: 1.0
Code example:
/* Creates a new NDEF record. */ var newRecord = new tizen.NDEFRecordURI("https://www.tizen.org/"); var payload = newRecord.payload;
2.10. NDEFRecordMedia
[Constructor(DOMString mimeType, byte[] data)] interface NDEFRecordMedia : NDEFRecord { readonly attribute DOMString mimeType; };
Since: 1.0
Constructors
Attributes
-
readonly
DOMString mimeTypeThe mime type [RFC 2046] (for example, text/plain, image/jpeg ).
Since: 1.0
Code example:
var myData = [116, 105, 122, 101, 110]; var newRecord = new tizen.NDEFRecordMedia("text/plain", myData);
2.11. HCEEventData
[NoInterfaceObject] interface HCEEventData { readonly attribute HCEEventType eventType; readonly attribute byte[] apdu; readonly attribute long length; };
Since: 2.3.1
Remark: Example of using can be find at HCEEventReceiveCallback code example.
Attributes
-
readonly
HCEEventType eventTypeHCE event type.
Since: 2.3.1
-
readonly
byte[]
apduThe bytes array of APDU
Since: 2.3.1
-
readonly
long lengthThe length of APDU
Since: 2.3.1
2.12. AIDData
[NoInterfaceObject] interface AIDData { readonly attribute SecureElementType type; readonly attribute AID aid; readonly attribute boolean readOnly; };
Since: 2.3.1
Remark: Example of using can be find at getAIDsForCategory code example.
Attributes
-
readonly
SecureElementType typeSecure Element type.
Since: 2.3.1
-
readonly
AID aidThe AID (Application ID) data, specified in ISO/IEC 7816-4
Since: 2.3.1
-
readonly
boolean readOnlyAn attribute to indicate whether the registered AID is read-only or not
Since: 2.3.1
2.13. NFCTagDetectCallback
[Callback, NoInterfaceObject] interface NFCTagDetectCallback { void onattach(NFCTag nfcTag); void ondetach(); };
Since: 1.0
This callback interface specifies two methods:
- onattach: Invoked when an NFC tag is detected
- ondetach: Invoked when an NFC tag is lost
It is used in NFCAdapter.setTagListener().
Methods
-
onattach
-
The method invoked when a tag is attached.
void onattach(NFCTag nfcTag);
Since: 1.0
Parameters:
- nfcTag: The attached NFC tag.
Code example:
try { var onSuccessCB = { onattach: function(nfcTag) { console.log("Successfully detected nfcTag type: " + nfcTag.type); } }; var adapter = tizen.nfc.getDefaultAdapter(); adapter.setTagListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
ondetach
-
The method invoked when the connected tag is detached.
void ondetach();
Since: 1.0
Code example:
try { var adapter; var onSuccessCB = { onattach: function(nfcTag) { console.log("Successfully detected nfcTag type: " + nfcTag.type); }, ondetach: function() { adapter.unsetTagListener(); } }; adapter = tizen.nfc.getDefaultAdapter(); adapter.setTagListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.14. NFCPeerDetectCallback
[Callback, NoInterfaceObject] interface NFCPeerDetectCallback { void onattach(NFCPeer nfcPeer); void ondetach(); };
Since: 1.0
This callback interface specifies two methods:
- onattach: Invoked when an NFC peer-to-peer target is detected
- ondetach: Invoked when an 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.
void onattach(NFCPeer nfcPeer);
Since: 1.0
Parameters:
- nfcPeer: The attached NFC peer-to-peer target.
Code example:
try { var adapter; var onSuccessCB = { onattach: function(nfcPeer) { console.log("Successfully detected nfcPeer: " + nfcPeer.isConnected); } }; adapter = tizen.nfc.getDefaultAdapter(); adapter.setPeerListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
-
ondetach
-
The method invoked when the connected NFC peer-to-peer target is detached.
void ondetach();
Since: 1.0
Code example:
try { var adapter; var onSuccessCB = { onattach: function(nfcPeer) { console.log("Successfully detected nfcPeer: " + nfcPeer.isConnected); }, ondetach: function() { adapter.unsetPeerListener(); } }; adapter = tizen.nfc.getDefaultAdapter(); adapter.setPeerListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.15. NDEFMessageReadCallback
[Callback=FunctionOnly, NoInterfaceObject] interface NDEFMessageReadCallback { void onsuccess(NDEFMessage ndefMessage); };
Since: 1.0
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.
void onsuccess(NDEFMessage ndefMessage);
Since: 1.0
Parameters:
- ndefMessage: NDEF message that is read from the NFC tag or target.
Code example:
try { var adapter; var readCallback = function(ndefMessage) { console.log("NDEFMessageReadCallback called successfully"); }; var tagListener = { onattach: function(nfcTag) { var result = nfcTag.readNDEF(readCallback); } }; adapter = tizen.nfc.getDefaultAdapter(); adapter.setTagListener(tagListener); } catch (err) { console.log(err.name + ": " + err.message); }
2.16. ByteArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ByteArraySuccessCallback { void onsuccess(byte[] data); };
Since: 1.0
This callback interface specifies a success method, with raw data as an input parameter. It is used in NFCTag.transceive().
Methods
-
onsuccess
-
The method invoked when the asynchronous call completes successfully.
void onsuccess(byte[] data);
Since: 1.0
Parameters:
- data: The raw data that is read from the NFC tag or response of a transceive operation.
Code example:
try { var successCB = function(data) { console.log("ByteArraySuccessCallback called successfully"); }; var message = [0x30, 0x00, 0x02, 0xa8]; /* READ command for MIFARE tags. */ nfcTag.transceive(message, successCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.17. CardEmulationModeChangeCallback
[Callback=FunctionOnly, NoInterfaceObject] interface CardEmulationModeChangeCallback { void onchanged(CardEmulationMode mode); };
Since: 2.3
Methods
-
onchanged
-
Called when the card emulation mode is changed.
void onchanged(CardEmulationMode mode);
Since: 2.3
Parameters:
- mode: Changed card emulation mode.
Code example:
try { var onSuccessCB = function(mode) { console.log("CardEmulationModeChangeCallback called successfully"); }; var listenerId = adapter.addCardEmulationModeChangeListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.18. TransactionEventCallback
[Callback=FunctionOnly, NoInterfaceObject] interface TransactionEventCallback { void ondetected(octet[] appletId, octet[] data); };
Since: 2.3
Methods
-
ondetected
-
Called when the asynchronous call completes successfully.
void ondetected(octet[] appletId, octet[] data);
Since: 2.3
Parameters:
- appletId: ID of the applet in which the transaction has happened.
- data: Transaction data.
Code example:
try { var onSuccessCB = function(aid, data) { console.log("TransactionEventCallback called successfully"); }; var listenerId = adapter.addTransactionEventListener("UICC", onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.19. ActiveSecureElementChangeCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ActiveSecureElementChangeCallback { void onchanged(SecureElementType type); };
Since: 2.3
Methods
-
onchanged
-
Called when the type of an active secure element is changed.
void onchanged(SecureElementType type);
Since: 2.3
Parameters:
- type: Type of a newly changed active secure element.
Code example:
try { var onSuccessCB = function(seType) { console.log("ActiveSecureElementChangeCallback called successfully"); }; var listenerId = adapter.addActiveSecureElementChangeListener(onSuccessCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.20. HCEEventReceiveCallback
[Callback=FunctionOnly, NoInterfaceObject] interface HCEEventReceiveCallback { void ondetected(HCEEventData data); };
Since: 2.3.1
Methods
-
ondetected
-
Called when HCE event is detected.
void ondetected(HCEEventData data);
Since: 2.3.1
Parameters:
- data: HCE event data.
Code example:
try { var onDetectedCB = function(event_data) { console.log("HCEEventReceiveCallback called successfully"); }; var listenerId = adapter.addHCEEventListener(onDetectedCB); } catch (err) { console.log(err.name + ": " + err.message); }
2.21. AIDArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface AIDArraySuccessCallback { void onsuccess(AIDData[] aids); };
Since: 2.3.1
Methods
-
onsuccess
-
The method invoked when the asynchronous call completes successfully.
void onsuccess(AIDData[] aids);
Since: 2.3.1
Parameters:
- aids: The list of AIDs.
Code example:
try { var successCB = function(aids) { console.log("AIDArraySuccessCallback called successfully"); }; adapter.getAIDsForCategory("HCE", "PAYMENT", successCB); } catch (err) { console.log(err.name + ": " + err.message); }
3. Related Feature
To guarantee that the NFC application runs on a device with the NFC feature, declare the following feature requirements in the config file:
To guarantee that the NFC application runs on a device with the NFC tag feature, declare the following feature requirements in the config file:
To guarantee that the NFC application runs on a device with the NFC p2p feature, declare the following feature requirements in the config file:
To guarantee that the NFC card emulation application runs on a device with the NFC card emulation feature, declare the following feature requirements in the config file:
To guarantee that the NFC host-based card emulation application runs on a device with the NFC host-based card emulation feature, declare the following feature requirements in the config file:
4. Full WebIDL
module NFC { typedef DOMString AID; 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" }; enum CardEmulationMode { "ALWAYS_ON", "OFF" }; enum SecureElementType { "ESE", "UICC", "HCE" }; enum CardEmulationCategoryType { "PAYMENT", "OTHER" }; enum HCEEventType { "DEACTIVATED", "ACTIVATED", "APDU_RECEIVED" }; Tizen implements NFCManagerObject; [NoInterfaceObject] interface NFCManagerObject { readonly attribute NFCManager nfc; }; [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; attribute CardEmulationMode cardEmulationMode raises(WebAPIException); attribute SecureElementType? activeSecureElement 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); long addCardEmulationModeChangeListener(CardEmulationModeChangeCallback changeCallback) raises(WebAPIException); void removeCardEmulationModeChangeListener(long watchId) raises(WebAPIException); long addTransactionEventListener(SecureElementType type, TransactionEventCallback eventCallback) raises(WebAPIException); void removeTransactionEventListener(long watchId) raises(WebAPIException); long addActiveSecureElementChangeListener(ActiveSecureElementChangeCallback changeCallback) raises(WebAPIException); void removeActiveSecureElementChangeListener(long watchId) raises(WebAPIException); NDEFMessage? getCachedMessage() raises(WebAPIException); void setExclusiveModeForTransaction(boolean mode) raises(WebAPIException); long addHCEEventListener(HCEEventReceiveCallback eventCallback) raises(WebAPIException); void removeHCEEventListener(long watchId) raises(WebAPIException); void sendHostAPDUResponse(byte[] apdu, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); boolean isActivatedHandlerForAID(SecureElementType type, AID aid) raises(WebAPIException); boolean isActivatedHandlerForCategory(SecureElementType type, CardEmulationCategoryType category) raises(WebAPIException); void registerAID(SecureElementType type, AID aid, CardEmulationCategoryType category) raises(WebAPIException); void unregisterAID(SecureElementType type, AID aid, CardEmulationCategoryType category) raises(WebAPIException); void getAIDsForCategory(SecureElementType type, CardEmulationCategoryType category, AIDArraySuccessCallback successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void setPreferredApp() raises(WebAPIException); void unsetPreferredApp() 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; }; [NoInterfaceObject] interface HCEEventData { readonly attribute HCEEventType eventType; readonly attribute byte[] apdu; readonly attribute long length; }; [NoInterfaceObject] interface AIDData { readonly attribute SecureElementType type; readonly attribute AID aid; readonly attribute boolean readOnly; }; [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); }; [Callback=FunctionOnly, NoInterfaceObject] interface CardEmulationModeChangeCallback { void onchanged(CardEmulationMode mode); }; [Callback=FunctionOnly, NoInterfaceObject] interface TransactionEventCallback { void ondetected(octet[] appletId, octet[] data); }; [Callback=FunctionOnly, NoInterfaceObject] interface ActiveSecureElementChangeCallback { void onchanged(SecureElementType type); }; [Callback=FunctionOnly, NoInterfaceObject] interface HCEEventReceiveCallback { void ondetected(HCEEventData data); }; [Callback=FunctionOnly, NoInterfaceObject] interface AIDArraySuccessCallback { void onsuccess(AIDData[] aids); }; };