NFC

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.

See the flowchart and code examples for method 1 and 2 in Code example.

eon_mobile_nfcex object

Properties
integer ii_errorcode

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.

integer ii_nfccardtype

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.

powerobject ipo_bindevent

The object to bind with the oe_newtagfound event and oe_error event.

string is_bindwitherrorevent

The name of the event bound with the oe_error event of the powerobject ipo_bindevent.

string is_bindwithnewtagfoundevent

The name of the event bound with the oe_newtagfound event of the powerobject ipo_bindevent.

string is_errortext

Error message which is returned when the oe_error event is triggered.

Events
oe_newtagfound

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

nfc

The name of the eon_mobile_nfcex object.

integer

ai_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.

Return value

None

oe_error

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.

Functions
of_addrecord

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

nfc

The name of the eon_mobile_nfcex object.

eon_mobile_str_nfcrecord

astr_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.

of_close

Description

Closes the NFC communication.

Supported on mobile client only.

Syntax

nfc.of_close ( )

Argument Type

Argument

Description

eon_mobile_nfcex

nfc

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.

of_getblocksize

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

nfc

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.

of_getmaxblockcount

Description

Gets the total number of blocks.

Supported on mobile client only.

Syntax

nfc.of_getmaxblockcount ( )

Argument Type

Argument

Description

eon_mobile_nfcex

nfc

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.

of_getmaxsectorcount

Description

Gets the total number of sectors.

Supported on mobile client only.

Syntax

nfc.of_getmaxsectorcount ( )

Argument Type

Argument

Description

eon_mobile_nfcex

nfc

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.

of_getndefrecord

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

nfc

The name of the eon_mobile_nfcex object.

integer

ai_index

The record index which is obtained through of_getndefrecordcount.

Record indexes are sequential numbers starting from 1.

eon_mobile_str_nfcrecord

astr_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.

of_getndefrecordcount

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

nfc

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.

of_getsize

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

nfc

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.

of_gettagid

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

nfc

The name of the eon_mobile_nfcex object.

string

as_tagid

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.

of_gettimeout

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

nfc

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.

of_open

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

nfc

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.

of_readblock

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

nfc

The name of the eon_mobile_nfcex object.

integer

ai_block

The block index which is obtained through of_getMaxBlockCount.

Block indexes are sequential numbers starting from 1.

blob

abl_data

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.

of_register

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

nfc

The name of the eon_mobile_nfcex object.

powerobject

apb_bind

The object to be bound with the oe_newtagfound event and the oe_error event.

string

as_newtagfound

The event to be bound with the oe_newtagfound event.

string

as_error

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.

of_setkey

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

nfc

The name of the eon_mobile_nfcex object.

string

as_key

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.

of_settimeout

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

nfc

The name of the eon_mobile_nfcex object.

integer

ai_timeout

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.

of_startblockoperate

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

nfc

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.

of_stopblockoperate

Description

Stops reading/writing data from the block.

Supported on mobile client only.

Syntax

nfc.of_stopblockoperate ( )

Argument Type

Argument

Description

eon_mobile_nfcex

nfc

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.

of_triggerevent

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

nfc

The name of the eon_mobile_nfcex object.

string

as_event

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.

of_writeblock

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

nfc

The name of the eon_mobile_nfcex object.

integer

ai_block

The block index which is obtained through of_getMaxBlockCount.

Block indexes are sequential numbers starting from 1.

blob

abl_data

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.

of_writerecords

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

nfc

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.

Structures
eon_mobile_str_nfcrecord

Description

Structure.

The record to be added.

Property

Type

Variable Name

Description

int

i_messagetype

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

s_Domain

This parameter is required when i_messagetype is External message.

string

s_Type

Data type or MIME type. This parameter is required when i_messagetype is Mime message or External message.

string

s_Payload

Valid data.

Code example

Below flowchart illustrates how NFC functionality works.

Figure 15. NFC flowchart

NFC flowchart

  • 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()