Provides access to Near Field Communication (NFC) functionality, allowing the applications to read NDEF message from the Android device.
Note: iOS devices have no NFC features at all, therefore, the NFC APIs are for the Android-powered device only, however, not every Android-powered device provides NFC functionality. For more information, see the Near Field Communication guide.
There are two methods to read/write data from the NFC tag. Pay attention to the functions listed below, because they are effective for one method only. The functions not listed below are effective for both methods, such as of_open, of_close, of_getblocksize, of_getmaxblockcount, of_getmaxsectorcount, of_getsize, of_gettagid.
-
Method 1: Read/write data in NDEF (NFC Data Exchange Format)
The following functions are effective for this method only:
-
Method 2: Read/write data in bytes from blocks
The following functions are effective for this method only:
See the flowchart and code examples for method 1 and 2 in Code example.
Error code which is returned when the oe_error event is triggered.
0 - Exception. Exception occurs during operation. The error message will be returned by the Android OS.
1 - ServiceDisable. NFC service is not enabled or the current device does not support NFC.
2 - DomainInvalid. Domain is invalid or contains illegal characters such as colon.
3 - MIMETypeInvalid. MIME type cannot be empty or contain multi-byte characters.
NFC card type.
0 - MifareClassic. Requires the encryption key, or uses the default key.
1 - MifareUltralight. Requires no encryption key.
2 - NfcV. Requires no encryption key.
3 - NDEFOnly. Supports read/write NDEF records but does not support read/write data (in bytes) from the block.
4 - UNKNOWN. Unrecognizable tag types. Cannot read/write from the tag, but can get tag identifier.
The object to bind with the oe_newtagfound event and oe_error event.
The name of the event bound with the oe_error event of the powerobject ipo_bindevent.
The name of the event bound with the oe_newtagfound event of the powerobject ipo_bindevent.
Error message which is returned when the oe_error event is triggered.
Description
Automatically occurs when the NFC tag is detected by the reader. Note: This event is triggered internally and automatically.
Syntax
nfc.oe_newtagfound (
integer
ai_type )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
integer |
|
0 - MifareClassic. Requires the encryption key, or uses the default key. 1 - MifareUltralight. Requires no encryption key. 2 - NfcV. Requires no encryption key. 3 - NDEFOnly. Supports read/write NDEF records but does not support read/write data (in bytes) from the block. 4 - UNKNOWN. Unrecognizable tag types. Cannot read/write from the tag, but can get tag identifier. |
Return value
None
Description
It will be triggered automatically if there is an error when using the NFC functionality.
Supported on mobile client only.
Note: This event will update the value of is_errortext and ii_errorcode properties.
Syntax
None.
Return value
None.
Description
Adds the NDEF record.
Supported on mobile client only.
Syntax
nfc.of_addrecord (
eon_mobile_str_nfcrecord
astr_nfcrecord )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
eon_mobile_str_nfcrecord |
|
The record to be added. See variable list of eon_mobile_str_nfcrecord. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Closes the NFC communication.
Supported on mobile client only.
Syntax
nfc.of_close (
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the size (in bytes) of the block.
Supported on mobile client only.
Syntax
nfc.of_getblocksize
( )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
>0 - Returns the size (in bytes) of the block.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the total number of blocks.
Supported on mobile client only.
Syntax
nfc.of_getmaxblockcount
( )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
>0 - Returns the total number of blocks.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the total number of sectors.
Supported on mobile client only.
Syntax
nfc.of_getmaxsectorcount
( )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
>0 - Returns the total number of sectors.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the NDEF record. The records cannot be read right after they are written to the tag; the tag will need to be detected by the reader again, and then the records can be read by using this function.
Supported on mobile client only.
Syntax
nfc.of_getndefrecord
( integer ai_index, ref
eon_mobile_str_nfcrecord
astr_nfcrecord )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
integer |
|
The record index which is obtained through of_getndefrecordcount. Record indexes are sequential numbers starting from 1. |
|
eon_mobile_str_nfcrecord |
|
The record to be read. See variable list of eon_mobile_str_nfcrecord. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the total number of the NDEF records.
Supported on mobile client only.
Syntax
nfc.of_getndefrecordcount
( )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
>0 - Returns the total number of the NDEF records.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the total capacity (in bytes) of the tag.
Supported on mobile client only.
Syntax
nfc.of_getsize (
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
>0 - Returns the total capacity (in bytes) of the tag.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the unique identifier of the tag.
Supported on mobile client only.
Syntax
nfc.of_gettagid (
ref string as_tagid
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
string |
|
Returns the unique identifier of the tag; or returns empty string if it is called in PowerBuilder or Appeon Web or if there is any error. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Gets the timeout value for reading/writing data.
Supported on mobile client only.
Syntax
nfc.of_gettimeout (
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
>0 - Returns the timeout value for reading/writing data.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Starts the NFC communication. Make sure this function is called before the tag is detected, otherwise, the other functions (such as the read/write functions) will not take effect. If the tag is detected before this function is called, the tag will need to be detected again after this function is called.
Supported on mobile client only.
Syntax
nfc.of_open (
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Reads data (in bytes) from the block. Make sure of_startblockoperate is called before the tag is detected and this function is called.
The records cannot be read right after they are written to the tag; the tag will need to be detected by the reader again, and then the records can be read by using the of_readblock function.
Supported on mobile client only.
Syntax
nfc.of_readblock (
integer ai_block,
ref blob
abl_data )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
integer |
|
The block index which is obtained through of_getMaxBlockCount. Block indexes are sequential numbers starting from 1. |
|
blob |
|
Data that are read from the block. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Binds user-defined events with the oe_newtagfound event and the oe_error event.
After oe_newtagfound and oe_error are triggered, the bound events will be triggered automatically. The bound events can be utilized to extend the events of the NFC object, as the NFC object is an NVO object which cannot be extended in the PB IDE. If you do not want to extend the events, then you do not need to call the of_register function, as it will be called internally and automatically.
Supported on mobile client only.
Syntax 1
nfc.of_register (
powerobject apb_bind,
string
as_newtagfound )
Syntax 2
nfc.of_register
( powerobject apb_bind,
string
as_newtagfound, string
as_error )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
powerobject |
|
The object to be bound with the oe_newtagfound event and the oe_error event. |
|
string |
|
The event to be bound with the oe_newtagfound event. |
|
string |
|
The event to be bound with the oe_error event. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Sets the read/write encryption key.
Supported on mobile client only.
Syntax
nfc.of_setkey (
string
as_key
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
string |
|
Encryption key for reading/writing data. Or use the system default key. MIFARE Classic tags require the key. Tag types can be obtained through oe_newtagfound event. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Sets the timeout value for reading/writing data.
Supported on mobile client only.
Syntax
nfc.of_settimeout (
integer
ai_timeout
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
integer |
|
Timeout value for reading/writing data. Normally, this parameter needs not to be set. Only if the read/write operation would take a long time, then this parameter should be set, otherwise the operation will time out and disconnect automatically. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Starts reading/writing data from the block. This function must be called before of_writeblock or of_readblock is called.
Supported on mobile client only.
Syntax
nfc.of_startblockoperate
( )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Stops reading/writing data from the block.
Supported on mobile client only.
Syntax
nfc.of_stopblockoperate
( )
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Triggers the object events bound with the oe_newtagfound event.
Supported on mobile client only.
Syntax
nfc.of_triggerevent
( string
as_event
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
string |
|
The event name bound with oe_newtagfound event. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Writes data (in bytes) to the block. Before this function is called, make sure of_startblockoperate is called first, otherwise this function will not take effect.
After the records are successfully written to the tag, they cannot be read immediately, the tag will need to be detected by the reader again, and then the records can be read successfully by using the of_readblock function.
Supported on mobile client only.
Syntax
nfc.of_writeblock (
integer
ai_block,
blob
abl_data
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
|
integer |
|
The block index which is obtained through of_getMaxBlockCount. Block indexes are sequential numbers starting from 1. |
|
blob |
|
Data to be written to the block. Block size should be obtained through of_getBlockSize first. Block size can be 4 bytes or 16 bytes. Data exceeding the block size will be automatically truncated. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Writes the NDEF record. of_addrecord should be called first to add one or more records, then of_writerecords should be called to write all records at one time. After the records are successfully written to the tag, they cannot be read immediately, the tag will need to be detected by the reader again, and then the records can be read successfully by using the of_getndefrecord function.
Supported on mobile client only.
Syntax
nfc.of_writerecords
(
)
|
Argument Type |
Argument |
Description |
|---|---|---|
|
eon_mobile_nfcex |
|
The name of the eon_mobile_nfcex object. |
Return value
Integer.
1 - Success.
-1 - It is called in PowerBuilder or Appeon Web, or there is an error.
Description
Structure.
The record to be added.
Property
|
Type |
Variable Name |
Description |
|---|---|---|
|
int |
|
0 - URL message 1 - Mime message 2 - App message 3 - Text message 4 - Poster message 5 - Alternative carrier message 6 - Handover carrier message 7 - Handover request 8 - Handover select 9 - External message |
|
string |
|
This parameter is required when
|
|
string |
|
Data type or MIME type. This parameter is
required when |
|
string |
|
Valid data. |
Below flowchart illustrates how NFC functionality works.
-
of_open: it must be called before the NFC tag is detected, otherwise, the other functions (such as the read/write functions) will not take effect. If the NFC tag is detected before this function is called, the tag will need to be detected again after this function is called.
-
of_addrecord and of_writerecords: of_addrecord should be called first to add one or more records, then of_writerecords should be called to write all records at one time.
-
of_getndefrecord: After the records are successfully written to the tag, they cannot be read immediately, the tag will need to be detected by the reader again, and then the records can be read successfully by the of_getndefrecord function.
-
of_startblockoperate: it must be called before of_writeblock or of_readblock is called, otherwise of_writeblock and of_readblock will not take effect.
-
of_readblock: After the records are successfully written to the tag, they cannot be read immediately, the tag will need to be detected by the reader again, and then the records can be read successfully by the of_readblock function.
Code example for method 1: Read/write data in NDEF (NFC Data Exchange Format)
eon_mobile_nfcex Inv_mobile_nfc //create nfc object eon_mobile_str_nfcrecord istr_nfcrecord //open nfc object Inv_mobile_nfc.of_open() //read nfc tag record, li_index is the index of the block which you want to get. Inv_mobile_nfc.of_getNdefRecord(li_index,istr_nfcrecord) //write nfc tag record Inv_mobile_nfc.of_addrecord(istr_nfcrecord) Inv_mobile_nfc.of_writeRecords() //close nfc object Inv_mobile_nfc.of_close()
Code example for method 2: Read/write data in bytes from blocks
eon_mobile_nfcex Inv_mobile_nfc //create nfc object eon_mobile_str_nfcrecord istr_nfcrecord //open nfc object Inv_mobile_nfc.of_open() //if necessary Inv_mobile_nfc.of_setTimeout(li_timeout) Inv_mobile_nfc.of_setkey(ls_key) Inv_mobile_nfc.of_startBlockOperate() //read nfc tag record Inv_mobile_nfc.of_readBlock(li_block,ibl_data) //write nfc tag record Inv_mobile_nfc.of_writeBlock(li_block,ibl_data) Inv_mobile_nfc.of_stopBlockOperate() //close nfc object Inv_mobile_nfc.of_close()
