doc/nfc.txt in rhodes-3.0.2 vs doc/nfc.txt in rhodes-3.1.0.beta.1

- old
+ new

@@ -1,544 +1,1648 @@ -# NFC +# NFC Developer Guide -## NFC Overview -NFC (Near Field Communication). NFC API provide access to NFC functionality. You can check NFC availability on current device and register callback for listen event when NFC tag near of device. Currently NFC supported only on Android. And also Android version must be 2.3.3 or later. -NFC API implemented in native extension. You should add "nfc" to extension list in your nuild.yml before start using NFC in your application. And also do not forget enable NFC for start process NFC events - Rho::NFCManager.enable. -NFC Ruby API based on Android NFC API. We recommended investigate Android doc for understand NFC Techs etc. See [Android NFC](http://developer.android.com/guide/topics/nfc/index.html) +The Near Field Communications (NFC) API allows you to use NFC functionality in your Rhodes application. With the NFC API, you can check to see if the mobile device supports NFC, and if so, have it listen for an NFC tag and register a callback if it finds one. You can also have your device push out an NFC tag. -NOTE: Before start using of NFC functionality, do not forget check current platform for supporting of NFC ! Use this : Rho::NFCManager.is_supported +Example Code +----------- +Example code for NFC is located here. -## NFC events -There are two different NFC callback can be received (you should setup callbacks before!) : -* NFC callback : it executed when Android ACTION_NDEF_DISCOVERED or ACTION_TAG_DISCOVERED events processed. -* NFC Tech callback : it executed when Android ACTION_TECH_DISCOVERED event processed. -In case of current state of NFC support in Android you can receive NFC callback only if your application in foreground. If your application is not run or in background - only ACTION_TECH_DISCOVERED is processed. -For process ACTION_TECH_DISCOVERED event you should setup list of techs in special resource file : [Rhodes ROOT]/lib/extensions/nfc/ext/nfc/platform/android/additional_files/res/xml/filter_nfc.xml. See according Android documentation - [Android ACTION_TECH_DISCOVERED description](http://developer.android.com/reference/android/nfc/NfcAdapter.html#ACTION_TECH_DISCOVERED) -For processing events received when application not run or in background, after start/activate use special method of NfcManager : + * [Rhodes Webinar Sample: NFC](https://github.com/rhomobile/webinar-samples/tree/master/nfc-rhodes) + * [Rhodes System API Samples: NFC](https://github.com/rhomobile/rhodes-system-api-samples/tree/master/app/Nfc) +## Generating a Container Model for NFC + +To create a Rhodes NFC application, you generate a Rhodes application, then you generate an NFC model in that application. Note that the model attributes are stubs in this case; you might not use the model attribute code that is generated. + + :::term + $ rhodes app nfc + + $ (the command line now shows the app being generated) + + $ cd nfc + $ rhodes model stub1 stub2 + +## Setting up build.yml + +NFC is currently supported only on the Android platform, OS version 2.3.3 or later. You must edit the Android section in your build.yml file for NFC. The version must be 2.3.3 or later, and NFC must be in the extension list. + + :::text + android: + version: 2.3.3 + extensions: + - nfc + +## Enabling NFC on the Mobile Device + +Before you can send or receive NFC tags on your NFC-capable mobile device, you must enable NFC on the device with the method NFCManager.enable. Also, when your application is in the background, you should enable it to receive NFC tag messages with the method NFCManager.perform_open_application_event. + +Rhodes has a hook called on_activate_app that is called every time an application using this hook launches, and when that application comes in from the background. You can call this hook in app/application.rb. + :::ruby - Rho::NFCManager.perform_open_application_event + def on_activate_app + # enable NFC on your NFC-capable mobile device + Rho::NFCManager.enable + + # Set the method to call for nfc callback + Rho::NFCManager.set_nfc_callback("/app/Nfc/nfc_callback") + + # Enable listening for events when the application is in the background + Rho::NFCManager.perform_open_application_event + end -In Tech callback access to Techs by get current Tag and request tech list/tech suport objects like this : +You can use the method NFCManager.is_supported to see if NFC is supported on your mobile device, and the method NFCManager.is_enabled to see if NFC has been enabled. The method NFCManager.disable disables NFC on your mobile device. +## Setting NFC Callback Methods + +If your method is going to read or write NFC tags, it also needs to set the callback methods that process the NFC tag. The NFCManager.set_nfc_tech_callback is for reading and writing NFC tags (when the Android ACTION_TECH_DISCOVERED event is processed). NFCManager.set_nfc_callback is for peer-to-peer communication (when the Android ACTION_NDEF_DISCOVERED or ACTION_TAG_DISCOVERED events are processed). + +For NFCManager.set_nfc_tech_callback (the Android ACTION_TECH_DISCOVERED event), set up your list of techs in a resource file : [Rhodes ROOT]/lib/extensions/nfc/ext/nfc/platform/android/additional_files/res/xml/filter_nfc.xml. Refet to the Android documentation - [Android ACTION_TECH_DISCOVERED description](http://developer.android.com/reference/android/nfc/NfcAdapter.html#ACTION_TECH_DISCOVERED). Here is an example. + + :::xml + <?xml version="1.0" encoding="utf-8"?> + <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> + <!-- capture all MIFARE Classics with NDEF payloads --> + <tech-list> + <tech>android.nfc.tech.MifareClassic</tech> + <tech>android.nfc.tech.Ndef</tech> + </tech-list> + </resources> + +You will write the callback methods in your NFC controller method to process your NFC tags: the example below points to the callback methods nfc_callback and nfc_tech_callback in the app/Nfc/nfc_controller.rb file. You can set the NFC callback methods in on_activate_app. + :::ruby + def on_activate_app + # enable NFC on your NFC-capable mobile device + Rho::NFCManager.enable + + # Set the method to call upon an nfc callback + Rho::NFCManager.set_nfc_callback("/app/Nfc/nfc_callback") + + # Set the method to call upon an nfc tech callback + Rho::NFCManager.set_nfc_tech_callback("/app/Nfc/nfc_tech_callback") + + # Enable listening for events when the application is in the background + Rho::NFCManager.perform_open_application_event + end + +Callbacks can be simple. You could just have the callback method say that it received a tag: + + :::ruby + def nfc_callback + @log = "TAG received: #{Time.now.strftime('%H:%M:%S')}" + add_to_log(@log) + end + +But to read or write NFC message and records from the NFC tag, you first get the current tag, determine the type of tag, and connect to the tag. + +## Getting, Determining Type of, and Connecting to a Tag + +Before you read from or write to a tag, get the tag with the method NFCManager method get_current_Tag. Find out what tech the tag uses with the method NFCTag.get_tech; the tag techs are listed in the NFCTagTechnology class. In this example, the tag is Ndef tech. Connect to the tag with the method NFCTagTechnology.connect. + + :::ruby tag = Rho::NFCManager.get_current_Tag - mifareClassic = tag.get_tech(Rho::NFCTagTechnology::MIFARE_CLASSIC) - if mifareClassic != nil - puts 'MifareClassic is supported !' - mifareClassic.connect + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + # read or write the NFC tag + end -## NdefMessage NdefRecord +You can now read from or write to the NFC tag. -NFC Message contain list of NdefRecord. You can read/write NdefMessage when you access to Tag via Ndef/NdefFormatable techs. Also you should send NdefMessage when you use P2P NFC functionality. -Example of construct NdefMessage for P2P send: +## Reading an NFC Tag +After you get a tag, determine its type, and connect to the tag, you can read from the tag. + +### Read the Tag Message and Get Its Records + +In this example, it is an Ndef tag, so use the NTagTechnology_Ndef.read_NdefMessage method (subclass of NFCTechnology) to read the message. Then get the records from that message: since this is an Ndef tag, use the NTagTechnology_Ndef.get_records method. + :::ruby + # read the ndef tag message and get the records from it. + msg = ndef.read_NdefMessage + records = msg.get_records + +### Iterate Through the Records and Hash Them + +Iterate through the records in the message (in the following example, the message has only one record). And since this is an Ndef record, use the NdefRecord method make_hash to make a hash of the record. + + :::ruby + # iterate through the array of records and hash the record + # this example has only one tag, so the array has only one element + r_a = [] + records.each do |record| + r_a << record.make_hash + end + +### Grab the Payload from the Hash + +In the case of the Ndef record, grab the payload from the hash with the payload_as_string part of the hash. + + :::ruby + # assign to a variable and print it out + msg_hash = { 'records' => r_a } + puts "records after processing: #{msg_hash.inspect}" + # Assign the string payload from the hash to the result + result = "Tag Result: " + msg_hash['records'][0]['payload_as_string'] if msg_hash['records'].size > 0 + +## Writing an NFC tag + +After you get a tag, determine its type, and connect to the tag, you can write to the tag. + +To write to an NFC tag, you fill the tag with a message that you create and load with payloads. + +### Creating a Message for the NFC tag + +For an Ndef record, you make payloads for the records in the message. You have several methods you can use to make the payload; the example here uses the NFCManager.make_payload_with_well_known_uri method. The NFC tag will contain the URL for Rhomobile. + + :::ruby payload = Rho::NFCManager.make_payload_with_well_known_uri(0, 'http://www.rhomobile.com') + +### Putting the Payload Into The Record + +For a Ndef record, make a hash and put the payload into it. + + :::ruby + hash = { 'id' => [0], 'type' => Rho::NdefRecord::RTD_URI, 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, 'payload' => payload} + +### Making the Records, Put Records into an Array, Make a Message + +Then make a record from the hash with the NFCManager method make_NdefRecord_from_hash, put the record(s) into an array, and make a message from the array with the NFCManager method make_NdefMessage_from_array_of_NdefRecord(records). + + :::ruby + record = Rho::NFCManager.make_NdefRecord_from_hash(hash) + records = [record] + msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) + +### Writing the NFC Message + +Once an Ndef message is created, you can write it with the NFCTagTechnology_Ndef method write. + + :::ruby + ndef.write_NdefMessage(msg) + puts ' finish write NdefMessage' + +## Closing the Connection to the Tag + +When you are done reading or writing to the NFC tag, close the connection to it with the NFCTagTechnology method close. + + :::ruby + ndef.close + +For example, you can have the following code in your NFC controller method to process NFC tech callbacks. + + :::ruby + def nfc_tech_callback + # Get the current tag + tag = Rho::NFCManager.get_current_Tag + # get the tag technology to find out how to process it; it is an ndef tag + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + # connect to the ndef tag + ndef.connect + #... read from or write to the NFC tag + ndef.close + end + #... + end + +## Pushing a Peer-to-Peer NFC Tag + +You can push an NFC tag to another NFC-enabled device with the NFCManager. p2p_enable_foreground_nde_push(msg) method. + +First, you need to make the payload for the message. + + :::ruby + def start_nfc_push + puts "Sending #{@params['push'].inspect}..." + payload = Rho::NFCManager.make_payload_with_well_known_text("en", @params['push']) + #... more processing + end + +Then put the payload into the record. This is an Ndef example, so we make a hash, then use the NFCManager.make_NdefRecord_from_hash method to create the record. + + :::ruby + hash = { + 'id' => [0], + 'type' => Rho::NdefRecord:: RTD_TEXT, + 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, + 'payload' => payload + } + record = Rho::NFCManager.make_NdefRecord_from_hash(hash) + +Make the record array, then use the NFCManager. make_NdefMessage_from_array_of_NdefRecord(records) method to make the message from the record array. + + :::ruby + records = [record] + msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) + +Now you can push the message with the NFCManager. p2p_enable_foreground_nde_push(msg) method. + + :::ruby + # start push message + Rho::NFCManager.p2p_enable_foreground_nde_push(msg) + @notice = "Started push." + render :action => :index + end + +And when you want to stop pushing the message, use the NFCManager. p2p_disable_foreground_nde_push method. + + :::ruby + def stop_nfc_push + Rho::NFCManager.p2p_disable_foreground_nde_push + @notice = "Stopped push." + render :action => :index + end + +## NdefRecord Class API + +The NdefRecord class contains methods for getting data from NFC Ndef tag records. + +An Ndef record consists of a hash: + + :::ruby + ID = 'id' + TNF = 'tnf' + TYPE = 'type' + PAYLOAD = 'payload' + +The Type Name Format (TNF part of the hash) is a 3-bit field that indicates how you interprete the type field (TYPE). Here is a list of the TNF values. + + :::ruby + TNF_ABSOLUTE_URI = 3 + TNF_EMPTY = 0 + TNF_EXTERNAL_TYPE = 4 + TNF_MIME_MEDIA = 2 + TNF_UNCHANGED = 6 + TNF_UNKNOWN = 5 + TNF_WELL_KNOWN = 1 + +The RTD text type (TYPE part of the hash) is used with the TNF_WELL_KNOWN value. + + :::ruby + RTD_TEXT = [0x54] # "T" + RTD_URI = [0x55] # "U" + RTD_SMART_POSTER = [0x53, 0x70] # "Sp" + RTD_ALTERNATIVE_CARRIER = [0x61, 0x63] # "ac" + RTD_HANDOVER_CARRIER = [0x48, 0x63] # "Hc" + RTD_HANDOVER_REQUEST = [0x48, 0x72] # "Hr" + RTD_HANDOVER_SELECT = [0x48, 0x73] # "Hs" + +Here is some code that creates a hash for an NdefRecord, which will be part of an NFCMessage to be pushed to an NFC-capable mobile device. + + :::ruby hash = { 'id' => [0], 'type' => Rho::NdefRecord::RTD_URI, 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, 'payload' => payload} - record = Rho::NFCManager.make_NdefRecord_from_hash(hash) - records = [record] - msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) - # start push message - Rho::NFCManager.p2p_enable_foreground_nde_push(msg) - -## NFC API +### NdefRecord get methods +You can extract data from an Ndef record with the following methods: + :::ruby - module Rho - - - class NdefRecord - - # 3-bit TNF (Type Name Format) field: Indicates how to interpret the type field - TNF_ABSOLUTE_URI = 3 - TNF_EMPTY = 0 - TNF_EXTERNAL_TYPE = 4 - TNF_MIME_MEDIA = 2 - TNF_UNCHANGED = 6 - TNF_UNKNOWN = 5 - TNF_WELL_KNOWN = 1 - - # RTD Text types. For use with TNF_WELL_KNOWN - RTD_TEXT = [0x54] # "T" - RTD_URI = [0x55] # "U" - RTD_SMART_POSTER = [0x53, 0x70] # "Sp" - RTD_ALTERNATIVE_CARRIER = [0x61, 0x63] # "ac" - RTD_HANDOVER_CARRIER = [0x48, 0x63] # "Hc" - RTD_HANDOVER_REQUEST = [0x48, 0x72] # "Hr" - RTD_HANDOVER_SELECT = [0x48, 0x73] # "Hs" - - ID = 'id' - TNF = 'tnf' - TYPE = 'type' - PAYLOAD = 'payload' - - - # return byte[] - def get_id - end - - # return int - def get_tnf - end - - # return byte[] - def get_type - end - - # return byte[] - def get_payload - end - - # return string - def get_payload_as_string - end - - # return raw byte[] - def get_byte_array - end - - # return hash - # hash : - # 'id' - byte[] - # 'tnf' - int - # 'type' - byte[] - # 'payload' - byte[] - # 'payload_as_string' - string - def make_hash - end - - # convert int tnf to string - def self.convert_Tnf_to_string(tnf) + get_id # returns byte[] + get_tnf # return int + get_type # returns byte[] + get_payload # returns byte[] + get_payload_as_string # returns string + get_byte_array # returns byte[] + +Example: + + :::ruby + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + type = ndef.get_type + #... + end + +### NdefRecord.make_hash + +The make_hash method returns a hash from an Ndef record, from which you can then extract data with the NdefRecord get methods. + +#### Returns + +A hash of the following format: + + * 'id' - byte[] + * 'tnf' - int + * 'type' - byte[] + * 'payload' - byte[] + * 'payload_as_string' - string + +#### Parameters + +None. + +#### Example + +This example steps through a records array, makes a hash of each record, and puts the hash into an array. + + :::ruby + r_a = [] + i = 0 + while i < records.size do + r_a << records[i].make_hash + i = i+1 + end + +### NdefRecord.convert_Tnf_to_string(int) + +Converts the int value of tnf from an Ndef record hash to a string. + +#### Returns + +A string. Text description of the Type Name Format (TNF). + +#### Parameters + +int: The tnf from a NdefRecord hash. + +#### Example + + :::ruby + puts 'tnf = '+Rho::NdefRecord.convert_Tnf_to_string(record['tnf']) + +### NdefRecord.convert_RTD_to_string(byte[]) + +Converts the byte[] value of rtd from an Ndef record hash to a string. + +#### Returns + +A string. Text description of the rtd (type part of the NdefRecord hash). + +#### Parameters + +byte[]: The rtd (type) from an NdefRecord hash. + +#### Example + + :::ruby + puts 'type = '+Rho::NdefRecord.convert_RTD_to_string(record['type']) + +## NdefMessage Class API + +Use the NdefMesage class to convert an NdefMessage into a format from which you can extract data. + +### NdefMessage.get_byte_array + +Converts an NdefMessage into a raw byte array. + +#### Returns + +byte[] - byte array containing the Ndef message. + +#### Parameters + +None. + +### NdefMessage.get_records + +Converts an NdefMessage into an NdefRecord array containing the records in the Ndef Message. + +#### Returns + +NdefRecord[] - NdefRecord array containing the records in an NdefMessage. + +#### Parameters + +None. + +#### Example + + :::ruby + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + msg = ndef.read_NdefMessage + records = msg.get_records + #... + end + +## NFCTagTechnology Class API + +Use the NFCTagTechnology to connect to NFC tags and to determine their type. + +### NFCTagTechnology Properties + +The NFCTagTechnology class has several properties to determine the type of the NFC tag. + + * ISODEP = 'IsoDep' + * MIFARE_CLASSIC = 'MifareClassic' + * MIFARE_ULTRALIGHT = 'MifareUltralight' + * NDEF = 'Ndef' + * NDEF_FORMATABLE = 'NdefFormatable' + * NFCA = 'NfcA' + * NFCB = 'NfcB' + * NFCF = 'NfcF' + * NFCV = 'NfcV' + +### NFCTagTechnology.get_name + +This method gets the name of an NFC tag. + +#### Returns + +String - the name of the NFC tag. + +#### Parameters + +None. + +### NFCTagTechnology.connect + +This method connects to an NFC tag. + +#### Returns + +None. + +#### Parameters + +None. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + puts ' Ndef is supported !' + ndef.connect + connected = ndef.is_connected + puts ' Ndef.isConnected() = '+connected.to_s + #... end - - # convert byte[] type to string - def self.convert_RTD_to_string(rtd) - end - - end + #... + end + +### NFCTagTechnology.close + +Closes a connection with an NFC tag. + +#### Returns + +None. + +#### Parameters + +None. + +#### Example + + :::ruby + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + msg = ndef.read_NdefMessage + records = msg.get_records + r_a = [] + records.each do |record| + r_a << record.make_hash + end + msg_hash = { 'records' => r_a } + result = "Tag Result: " + msg_hash['records'][0]['payload_as_string'] if msg_hash['records'].size > 0 + + ndef.close + +### NFCTagTechnology.is_connected + +This method returns true if the application is connected with an NFC tag, false otherwise. + +#### Returns + +True or false. + +#### Parameters + +None. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + connected = ndef.is_connected + puts ' Ndef.isConnected() = '+connected.to_s + +## NFCTagTechnology_NfcA Class API - - class NdefMessage - - - # return raw byte[] - def get_byte_array - end - - # return array of NdefRecord - def get_records - end - - - end - - - - class NFCTagTechnology - - ISODEP = 'IsoDep' - MIFARE_CLASSIC = 'MifareClassic' - MIFARE_ULTRALIGHT = 'MifareUltralight' - NDEF = 'Ndef' - NDEF_FORMATABLE = 'NdefFormatable' - NFCA = 'NfcA' - NFCB = 'NfcB' - NFCF = 'NfcF' - NFCV = 'NfcV' - - # return string - def get_name +Subset of NFCTagTechnology class. + +### NFCTagTechnology_NfcA.get_Atqa + +Gets a byte array containing Atqa. + +#### Returns + +byte[] - Atqa. + +#### Parameters + +None. + +### NFCTagTechnology_NfcA.get_Sak + +Gets a int containing Sak. + +#### Returns + +int - Sak. + +#### Parameters + +None. + +### NFCTagTechnology_NfcA.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTagTechnology_Ndef Class API + +Subset of NFCTagTechnology class. + +MIFARE_CLASSIC = 'com.nxp.ndef.mifareclassic' +NFC_FORUM_TYPE_1 = 'org.nfcforum.ndef.type1' +NFC_FORUM_TYPE_2 = 'org.nfcforum.ndef.type2' +NFC_FORUM_TYPE_3 = 'org.nfcforum.ndef.type3' +NFC_FORUM_TYPE_4 = 'org.nfcforum.ndef.type4' + +### NFCTagTechnology_Ndef.get_max_size + +Gets the maximum size of the Ndef tag. + +#### Returns + +int - Maximum size of the Ndef tag. + +#### Parameters + +None. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + puts ' Ndef is supported !' + ndef.connect + puts ' max_size = '+ndef.get_max_size.to_s + #... end - - # connect - only after it you can make any I/O operation - def connect + #... + end + +### NFCTagTechnology_Ndef.is_writable + +Returns true if the Ndef tag is writeable, false otherwise. + +#### Returns + +bool - True if the tag is writeable, false otherwise. + +#### Parameters + +None. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + puts ' Ndef is supported !' + ndef.connect + puts ' is_writable = '+ndef.is_writable.to_s + #... end - - # close connect - make it after your I/O operations - def close + #... + end + +### NFCTagTechnology_Ndef.can_make_read_only + +Returns true if the Ndef tag can be made read only, false otherwise. + +#### Returns + +bool - True if the tag can be made read only, false otherwise. + +#### Parameters + +None. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + puts ' Ndef is supported !' + ndef.connect + puts ' can_make_read_only = '+ndef.can_make_read_only.to_s + #... end - - # return true if tech connected and ready for I/O operations - def is_connected + #... + end + +### NFCTagTechnology_Ndef.make_read_only + +Returns true if the Ndef tag is made read only, false otherwise. + +#### Returns + +bool - True if the tag is made read only, false otherwise. + +#### Parameters + +None. + +### NFCTagTechnology_Ndef.get_type + +Returns a string containing the type of the Ndef tag. + +#### Returns + +string - The type of the Ndef tag. + +#### Parameters + +None. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + puts ' Ndef is supported !' + ndef.connect + type = ndef.get_type + puts ' type = '+type + #... end - + #... end - - class NFCTagTechnology_NfcA < NFCTagTechnology - - # return byte[] - def get_Atqa - end +### NFCTagTechnology_Ndef.read_NdefMessage + +Returns an NdefMessage read from an Ndef tag. + +#### Returns + +NdefMessage - The message contained in the Ndef tag. + +#### Parameters + +None. + +#### Example + + :::ruby + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + msg = ndef.read_NdefMessage + #... process the message + end + +### NFCTagTechnology_Ndef.write_NdefMessage(msg) + +Returns an NdefMessage read from an Ndef tag. + +#### Returns + +None. + +#### Parameters + +msg - an NdefMessage written to an Ndef tag. + +#### Example + + :::ruby + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + ndef.connect + #... create the message to write + ndef.write_NdefMessage(msg) + end + +## NFCTagTechnology_MifareClassic Class API + +Subset of NFCTagTechnology. + +### Constants + + :::term + KEY_DEFAULT = [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF] + KEY_MIFARE_APPLICATION_DIRECTORY = [0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5] + KEY_NFC_FORUM =[0xD3, 0xF7, 0xD3, 0xF7, 0xD3, 0xF7] - # return int - def get_Sak - end - - # data - byte[] - # return byte[] - def transceive(data) - end - - end +### Types + + :::term + TYPE_CLASSIC = 0 + TYPE_PLUS = 1 + TYPE_PRO = 2 + TYPE_UNKNOWN = -1 + +### NFCTagTechnology_MifareClassic.get_type + +Returns the type of a MifareClassic tag. + +#### Returns + +int - the tag type. + +#### Parameters + +None. + +### NFCTagTechnology_MifareClassic.convert_type_to_string(type) + +Returns the named type of a MifareClassic tag. + +#### Returns + +type - A string containing the tag type. + +#### Parameters + +None. + +### NFCTagTechnology_MifareClassic.write_block(index, block) + +Writes a block to a MifareClassic tag. + +#### Returns + +None. + +#### Parameters + +index - integer, the index to where in the tag sector the block will be written. +block - a 16 byte array written to the tag. + +### NFCTagTechnology_MifareClassic.read_block(index) + +Reads a block from a MifareClassic tag. + +#### Returns + +A 16 byte array. + +#### Parameters + +index - integer, the index to where in the tag sector the block is read from. + +### NFCTagTechnology_MifareClassic.get_size + +Return the size in bytes of a MifareClassic tag. + +#### Returns + +The size in bytes of a MifareClassic tag. + +#### Parameters + +None. + +### NFCTagTechnology_MifareClassic.get_block_count + +Return the number of blocks in a MifareClassic tag. + +#### Returns + +The number of blocks in a MifareClassic tag. + +#### Parameters + +None. + +### NFCTagTechnology_MifareClassic.get_sector_count + +Return the sector count in a MifareClassic tag. + +#### Returns + +The sector count in a MifareClassic tag. + +#### Parameters + +None. + +### NFCTagTechnology_MifareClassic.get_blocks_in_sector_count(index) + +Returns the number of blocks in a sector in a MifareClassic tag. + +#### Returns + +The number of blocks in the sector. + +#### Parameters + +index - the index to a sector. + +### NFCTagTechnology_MifareClassic.sector_to_block(index) + +Returns the index of the first block in a sector in a MifareClassic tag. + +#### Returns + +The index of the first block in a sector. + +#### Parameters + +index - the index to the current sector. - class NFCTagTechnology_Ndef < NFCTagTechnology - - MIFARE_CLASSIC = 'com.nxp.ndef.mifareclassic' - NFC_FORUM_TYPE_1 = 'org.nfcforum.ndef.type1' - NFC_FORUM_TYPE_2 = 'org.nfcforum.ndef.type2' - NFC_FORUM_TYPE_3 = 'org.nfcforum.ndef.type3' - NFC_FORUM_TYPE_4 = 'org.nfcforum.ndef.type4' - - # return int - def get_max_size - end - - # return bool - def is_writable - end - - # return bool - def can_make_read_only - end - - # return bool - def make_read_only - end - - # return string - def get_type - end - - # return NdefMessage - def read_NdefMessage - end - - # msg - NdefMessage - def write_NdefMessage(msg) - end - - - end - - - class NFCTagTechnology_MifareClassic < NFCTagTechnology +### NFCTagTechnology_MifareClassic.authenticate_sector_with_key_A(index, key) + +Authenticates a sector with a key. Returns true if the authenticate was passed. + +#### Returns + +True if the authenticate was passed. + +#### Parameters + +index - the index to the current sector. +key - a 6 byte array containing the key. + +### NFCTagTechnology_MifareClassic.authenticate_sector_with_key_B(index, key) + +Authenticates a sector with a key. Returns true if the authenticate was passed. + +#### Returns + +True if the authenticate was passed. + +#### Parameters + +index - the index to the current sector. +key - a 6 byte array containing the key. + +### NFCTagTechnology_MifareClassic.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTagTechnology_MifareUltralight Class API + +Subclass of NFCTagTechnology. - KEY_DEFAULT = [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF] - KEY_MIFARE_APPLICATION_DIRECTORY = [0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5] - KEY_NFC_FORUM =[0xD3, 0xF7, 0xD3, 0xF7, 0xD3, 0xF7] - - TYPE_CLASSIC = 0 - TYPE_PLUS = 1 - TYPE_PRO = 2 - TYPE_UNKNOWN = -1 - - # return int type type - def get_type - end - - # return named type (for known types) - def self.convert_type_to_string(type) - end - - # index - integer - # block - 16 byte array - def write_block(index, block) - end - - # index - integer - # return 16 byte array - def read_block(index) - end - - # return size in bytes - def get_size - end - - #return number of blocks - def get_block_count - end - - # return count of sectors - def get_sector_count - end - - # return count of blocks in sector - def get_blocks_in_sector_count(index) - end - - # return index of first block in sector - def sector_to_block(index) - end - - # authenticate sector with key - # key is 6 byte array - # return true if authenticate was passed - def authenticate_sector_with_key_A(index, key) - end - - # authenticate sector with key - # key is 6 byte array - # return true if authenticate was passed - def authenticate_sector_with_key_B(index, key) - end - - # send data (byte array) to Tag and receive result - byte array - def transceive(data) - end - - end - - class NFCTagTechnology_MifareUltralight < NFCTagTechnology - TYPE_ULTRALIGHT = 1 TYPE_ULTRALIGHT_C = 2 TYPE_UNKNOWN = -1 + +### NFCTagTechnology_MifareUltralight.get_type + +Returns the type of a MifareUltralight tag. + +#### Returns + +int - the tag type. + +#### Parameters + +None. + +### NFCTagTechnology_MifareUltralight.write_page(index, block) + +Write a page to a MifareUltralight tag. + +#### Returns + +None. + +#### Parameters + +index - integer +block - 4 byte array + +### NFCTagTechnology_MifareUltralight.read_page(index) + +Reads a page from a MifareUltralight tag. + +#### Returns + +16 byte array. + +#### Parameters + +index - integer + +### NFCTagTechnology_MifareUltralight.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTagTechnology_IsoDep Class API + +Subclass of NFCTagTechnology. + +### NFCTagTechnology_IsoDep.get_hi_layer_responce + +Returns the hi layer response. + +#### Returns + +byte[] - hi layer response. + +#### Parameters + +None. + +### NFCTagTechnology_IsoDep.get_historical_bytes + +Returns the historical bytes. + +#### Returns + +byte[] - historical bytes. + +#### Parameters + +None. + +### NFCTagTechnology_IsoDep.set_timeout(timeout) + +Sets a timeout. + +#### Returns + +None. + +#### Parameters + +int - the timeout. + +### NFCTagTechnology_IsoDep.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTagTechnology_NdefFormatable Class API + +Subclass of NFCTagTechnology. + +### NFCTagTechnology_NdefFormatable.format(msg) + +Formats a NdefMessage to NdefFormatable format. +QUESTION: Needs a correct definition. + +#### Returns + +None. + +#### Parameters + +msg - NdefMessage. + +### NFCTagTechnology_NdefFormatable.format_read_only(msg) + +Formats a NdefMessage to NdefFormatable read-only format. +QUESTION: Needs a correct definition. + +#### Returns + +None. + +#### Parameters + +msg - NdefMessage. - # return int - def get_type - end - - # index - integer - # block - 4 byte array - def write_page(index, block) - end - - # index - integer - # return 16 byte array - def read_pages(index) - end - - # send data (byte array) to Tag and receive result - byte array - def transceive(data) - end - - end - - - class NFCTagTechnology_IsoDep < NFCTagTechnology - - # return byte[] - def get_hi_layer_responce - end - - # return byte[] - def get_historical_bytes - end - - - # timeout - int - def set_timeout(timeout) - end - - # data - byte[] - # return byte[] - def transceive(data) - end - - end - - - class NFCTagTechnology_NdefFormatable < NFCTagTechnology - - # msg - NdefMessage - def format(msg) - end - - # msg - NdefMessage - def format_read_only(msg) - end - - end - - - class NFCTagTechnology_NfcB < NFCTagTechnology - - # return byte[] - def get_application_data - end - - # return byte[] - def get_protocol_info - end - - - # data - byte[] - # return byte[] - def transceive(data) - end - - end - - - class NFCTagTechnology_NfcF < NFCTagTechnology - - # return byte[] - def get_manufacturer - end - - # return byte[] - def get_system_code - end - - - # data - byte[] - # return byte[] - def transceive(data) - end - - end - - - class NFCTagTechnology_NfcV < NFCTagTechnology - - # return int - def get_dsf_id - end - - # return int - def get_responce_flags - end - - - # data - byte[] - # return byte[] - def transceive(data) - end - - end - - - - class NFCTag - - # return array of string - def get_tech_list - end - - # return byte[] - def get_ID - end - - # return object with implementation of requested tech (based on NFCTagTechnology) - def get_tech(tech_name) +## NFCTagTechnology_NfcB Class API + +Subclass of NFCTagTechnology. + +### NFCTagTechnology_NfcB.get_application_data + +Gets application data from an NfcB tag. + +#### Returns + +byte[] - the application data. + +#### Parameters + +None. + +### NFCTagTechnology_NfcB.get_protocol_info + +Gets protocol information from an NfcB tag. + +#### Returns + +byte[] - the protocol information. + +#### Parameters + +None. + +### NFCTagTechnology_NfcB.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTagTechnology_NfcF Class API + +Subset of NFCTagTechnology. + +### NFCTagTechnology_NfcF.get_manufacturer + +#### Returns + +byte[] - the manufacturer. + +#### Parameters + +None. + +### NFCTagTechnology_NfcF.get_system_code + +#### Returns + +byte[] - the system code. + +#### Parameters + +None. + +### NFCTagTechnology_NfcF.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTagTechnology_NfcV Class API + +Subset of NFCTagTechnology. + +### NFCTagTechnology_NfcV.get_dsf_id + +#### Returns + +int - the dsf ID. + +#### Parameters + +None. + +### NFCTagTechnology_NfcV.get_responce_flags + +#### Returns + +int - the response flags. + +#### Parameters + +None. + +### NFCTagTechnology_NfcV.transceive(data) + +Sends data (a byte array) to a tag and receives result in a byte array. + +#### Returns + +byte[] - data received from the tag. + +#### Parameters + +data - byte[] sent to the tag. + +## NFCTag Class API + +Use the NFCTag class to get the NFC tag in certain formats, such as Ndef. + +### NFCTag.get_tech(tech_name) + +This method returns an object with the implementation of the requested NFC tech based on the NFCTagTechnology class. + +#### Returns + +An object with the implementation of the requested NFC tech based on the NFCTagTechnology class. Refer to the NFCTagTechnology class for the types of NFC tech you can request. + +#### Parameters + +tech_name - Tech name based on the NFCTagTechnology class. + +#### Example + + :::ruby + tag = Rho::NFCManager.get_current_Tag + if tag != nil + ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF) + if ndef != nil + puts ' Ndef is supported !' + ndef.connect + connected = ndef.is_connected + puts ' Ndef.isConnected() = '+connected.to_s + #... read from or write to the tag end + +### NFCTag.get_tech_list + +This method returns a string array containing the NFC tag. + +#### Returns + +A string array containing the NFC tag. + +#### Parameters + +None. + +### NFCTag.get_ID + +This method returns a byte array containing the NFC tag ID. + +#### Returns + +byte[] - A byte array containing the NFC tag ID. + +#### Parameters + +None. + +## NFCManager Class API + +Use NFCManager to manage NFC messages and records that your NFC application sends and receives. + +Methods: + + * is_supported + * enable + * is_enabled + * disable + * set_nfc_callback(url) + * set_nfc_tech_callback(url) + * get_current_Tag + * perform_open_application_event + * p2p_enable_foreground_nde_push + * p2p_disable_foreground_nde_push + * make_NdefRecord_from_byte_array(array) + * make_NdefRecord_from_hash(hash) + * make_NdefMessage_from_array_of_NdefRecord(array) + * make_string_from_payload(payload, tnf, type) + * make_payload_with_absolute_uri(uri_string) + * make_payload_with_well_known_uri(prefix_code, uri_string) + * make_payload_with_well_known_text(language, text) + +### Callback Tag Message Storage + +The NFC callback stores the NFC tag messages in a hash array: + +@params['messages'] - array of NFC tag messages. Each message is a hash. + +The messages can be picked up in 'raw_message', an array of bytes containing the raw message. The messages can also be picked up in 'records', an array of records where each record is a hash. The records use the NFC Data Exchange Format. Each record has the following hash items. + + * 'raw_record' - Array of bytes. The raw record. + * 'id' - Array of bytes. The tag ID. + * 'payload' - Array of bytes. + * 'tnf' - Int. The Type Name Format. + * 'type' - array of bytes + * 'payload_as_string' - String. The message payload in a string (support special formats for URI, TEXT). + * 'subrecords' - message hash (only for SMART_POSTER type) + +### NFCManager.is_supported + +This method returns true if the mobile device supports NFC, false otherwise. + +#### Returns + +True or false. + +#### Parameters + +None. + +#### Example + + :::ruby + def index + $status = Rho::NFCManager.is_enabled.to_s + # See if NFC supported and save that info in a string + $supported = Rho::NFCManager.is_supported.to_s + $log = '' + Rho::NFCManager.set_nfc_callback(url_for(:action => :nfc_callback)) + Rho::NFCManager.set_nfc_tech_callback(url_for(:action => :nfc_tech_callback)) + puts 'NfcController.index' + render end - - - - - - class NFCManager - - - # return true/false - def self.is_supported + +### NFCManager.enable + +The enable method enables NFC event processing on your mobile device. Your nfc and nfc_tech callback methods are executed only if Rhodes NFC is enabled. On Android, when Rhodes NFC is enabled and the application activity is in the foreground, the activity gets high priority for NFC events. Android will not show additional UI for the select Activity for Tag processing; the Rhodes applciation will processed the tag. + +#### Returns + +None. + +#### Parameters + +None. + +#### Example + + :::ruby + # Enable NFC functionality and set up callbacks. + def on_activate_app + Rho::NFCManager.enable + Rho::NFCManager.set_nfc_callback("/app/Nfc/nfc_callback") + Rho::NFCManager.set_nfc_tech_callback("/app/Nfc/nfc_tech_callback") + Rho::NFCManager.perform_open_application_event + end + +### NFCManager.disable + +This method disables your application from receiving NFC events. Your application will not be able to receive NFC tags. + +#### Returns + +None. + +#### Parameters + +None. + +#### Example + + :::ruby + # Disable the NFC functionality and set a status string accordingly + def do_disable + Rho::NFCManager.disable + $status = Rho::NFCManager.is_disabled.to_s + set_status($status) + end + +### NFCManager.is_enabled + +This method returns true if the mobile device has been enabled for NFC, false otherwise. + +#### Returns + +True or false. + +#### Parameters + +None. + +#### Example + + :::ruby + def do_enable + Rho::NFCManager.enable + $status = Rho::NFCManager.is_enabled.to_s + set_status($status) + end + +### NFCManager.set_nfc_callback(string), NFCManager.set_nfc_tech_callback(string) + +The set_nfc_callback method tells your application what callback to perform when it receives an NFC tag and your application is in the foreground. set_nfc_callback executes when the Android events ACTION_NDEF_DISCOVERED or ACTION_TAG_DISCOVERED are processed. + +The set_nfc_tech_callback method tells your application what callback to perform when it receives an NFC tag and your application is in the background. The set_nfc_tech_callback method executes when the Android event ACTION_TECH_DISCOVERED is processed. + +#### Returns + +None. + +### Parameters + +string - url. The path to the method in the NFC controller that is executed on NFC callback. + +### Example: + + :::ruby + def on_activate_app + Rho::NFCManager.enable + + # Perform the nfc_callback or nfc_tech_callback method in + # nfc_controller.rb on nfc callback + Rho::NFCManager.set_nfc_callback("/app/Nfc/nfc_callback") + Rho::NFCManager.set_nfc_tech_callback("/app/Nfc/nfc_tech_callback") + + Rho::NFCManager.perform_open_application_event + end + +### NFCManager.get_current_Tag + +This method returns the current NFCTag that the mobile device has just read, or returns nil if no tag has been discovered. + +#### Returns + +NFCTag. An NFC tag. + +#### Parameters + +None. + +#### Example + + :::ruby + def nfc_tech_callback + @msg = 'Tech received! Reading tag...' + add_to_log(@msg) + tag = Rho::NFCManager.get_current_Tag + if tag != nil + @msg = test_ndef_read(tag) + else + @msg = "Tag is nil!" end + add_to_log(@msg) + end + +### NFCManager.perform_open_application_event + +Call the perform_open_application_event method to have your application listen for NFC tags when it is in the background. When your application is in the background or it has not started, then the NFC event was saved, and the application open/start process is executed. To process that NFC event, your application needs to call perform_open_application_event. + +#### Returns + +None. + +#### Parameters + +None. + +#### Example: + + :::ruby + def on_activate_app + Rho::NFCManager.enable + + # Perform the nfc_callback or nfc_tech_callback method in + # nfc_controller.rb on nfc callback + Rho::NFCManager.set_nfc_callback("/app/Nfc/nfc_callback") + Rho::NFCManager.set_nfc_tech_callback("/app/Nfc/nfc_tech_callback") + + Rho::NFCManager.perform_open_application_event + end + +### NFCManager.p2p_enable_foreground_nde_push(NDefMessage) + +The p2p_enable_foreground_nde_push method causes your mobile device to push an NFC message (NdefMessage) for any NFC-enabled device to receive. + +#### Returns + +None. + +#### Parameters + +NdefMessage - The NFC message that is pushed. + +#### Example + + :::ruby + def do_p2p_enable + # prepare NdefMessage for send to another device + payload = Rho::NFCManager.make_payload_with_well_known_uri(0, 'http://www.rhomobile.com') + hash = { 'id' => [0], 'type' => Rho::NdefRecord::RTD_URI, 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, 'payload' => payload} + record = Rho::NFCManager.make_NdefRecord_from_hash(hash) + records = [record] + msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) + # start push message + Rho::NFCManager.p2p_enable_foreground_nde_push(msg) + add_to_log('Enable PUSH P2P') + set_log($log) + end + +### NFCManager.p2p_disable_foreground_nde_push + +The p2p_disable_foreground_nde_push method causes your mobile device to stop pushing NFC messages to any other NFC-enabled devices that can receive them. + +#### Returns + +None. + +#### Parameters + + None. + +#### Example + + :::ruby + def do_p2p_disable + # stop push message + Rho::NFCManager.p2p_disable_foreground_nde_push + add_to_log('Disable PUSH P2P') + set_log($log) + end + +### NFCManager.make_NdefRecord_from_byte_array(array) + +The make_NdefRecord_from_byte_array method creates a record for an NFC tag message (NdefRecord) from a byte array. + +#### Returns + +NdefRecord - An Ndef record. + +#### Parameters + +array - a byte array containing a raw NFC record. + +### NFCManager.make_NdefRecord_from_hash(hash) + +The make_NdefRecord_from_hash method creates a record for an NFC tag message (NdefRecord) from a hash. + +#### Returns + +NdefRecord - An Ndef record. + +#### Parameters + +@params['Tag_event'] - 'discovered' + +@params['messages'] - array of messages. Each message is a hash. + * 'id' - Array of bytes. The tag ID. + * 'tnf' - Int. The Type Name Format. + * 'type' - Array of bytes. The payload type. + * 'payload' - Array of bytes. The message payload. + +#### Example + + :::ruby + def do_p2p_enable + # prepare an NdefMessage for sending to another device + payload = Rho::NFCManager.make_payload_with_well_known_uri(0, 'http://www.rhomobile.com') - def self.enable - end - - def self.disable - end - - # return true/false - def self.is_enabled - end - - # in callback - # @params['messages'] - array of messages (each message is hash) - # message hash items : - # 'raw_message' - array of bytes (raw message) - # 'records' - array of records (each record is hash) - # record hash items : - # 'raw_record' - array of bytes (raw record) - # 'id' - array of bytes - # 'payload' - array of bytes - # 'tnf' - int - # 'type' - array of bytes - # 'payload_as_string' - string, payload prepared to string (support specail formats for URI, TEXT) - # 'subrecords' - message hash (only for SMART_POSTER type) + # Create a hash -- id, tnf, type, payload -- for an NFC record + hash = { 'id' => [0], 'type' => Rho::NdefRecord::RTD_URI, 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, 'payload' => payload} - # set callback for tech events (Tag discovered/lost, tech special events) - def self.set_nfc_callback(callback_url) - end - - # in callback - # @params['Tag_event'] - 'discovered' - def self.set_nfc_tech_callback(callback_url) - end - - # return current discovered Tag or nil if not any Tag discovered now - def self.get_current_Tag - end - - # call this function after application is started and you setup all functionality for process NFC event - # when application in background or not started, then NFC event was saved and application open/start process executed - # for process saved event - call this function - def self.perform_open_application_event - end - - # ndef_message - NdefMessage - # start push NdefMessage to any receivers - def self.p2p_enable_foreground_nde_push(ndef_message) - end - - # stop any push NdefMessage to receivers - def self.p2p_disable_foreground_nde_push - end - - - # make NdefRecord from byte[] - def self.make_NdefRecord_from_byte_array(array) - end - - # make NdefRecord from hash - # hash : - # 'id' - byte[] - # 'tnf' - int - # 'type' - byte[] - # 'payload' - byte[] - def self.make_NdefRecord_from_hash(hash) - end - - # make NdefMessage from byte[] - def self.make_NdefMessage_from_byte_array(array) - end - - # make NdefMessage from NdefRecord[] - def self.make_NdefMessage_from_array_of_NdefRecord(array) - end - - # make string from byte[] payload - # tnf - int (from NdefRecord) - # type - byte[] (from NdefRecord) - def self.make_string_from_payload(payload, tnf, type) - end + # Create the NFC record with that hash + record = Rho::NFCManager.make_NdefRecord_from_hash(hash) + records = [record] - # prepare byte[] payload from string with Absolute URI - def self.make_payload_with_absolute_uri(uri_string) - end - - # prepare byte[] payload from int prefix code and string URI - def self.make_payload_with_well_known_uri(prefix_code, uri_string) - end - - # prepare byte[] payload from string language code and string text - def self.make_payload_with_well_known_text(language, text) - end - - + msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) + + # start push message + Rho::NFCManager.p2p_enable_foreground_nde_push(msg) end - + + +### NFCManager.make_NdefMessage_from_byte_array(array) + +The make_NdefMessage_from_byte_array method creates an NFC tag message (NdefMessage) from a byte array. + +#### Returns + +A NFC message (NdefMessage). + +#### Parameters + +array - a byte array containing a raw NFC message. + +### NFCManager.make_NdefMessage_from_array_of_NdefRecord(array) + +The make_NdefMessage_from_byte_array method creates an NFC tag message (NdefMessage) from an array of records (NdefRecord, such as what you get from make_NdefRecord_from_hash). + +#### Returns + +An NFC message (NdefMessage). + +#### Parameters + +array - an array of records (NdefRecord). + +#### Example + + :::ruby + def do_p2p_enable + # prepare an NdefMessage for sending to another device + payload = Rho::NFCManager.make_payload_with_well_known_uri(0, 'http://www.rhomobile.com') + # Create a hash -- id, tnf, type, payload -- for an NFC record + hash = { 'id' => [0], 'type' => Rho::NdefRecord::RTD_URI, 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, 'payload' => payload} + # Create the NFC record with that hash + record = Rho::NFCManager.make_NdefRecord_from_hash(hash) + records = [record] + # Create the NdefMessage from the NdefRecord (just one record in array) + msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) + # start push message + Rho::NFCManager.p2p_enable_foreground_nde_push(msg) + add_to_log('Enable PUSH P2P') + set_log($log) end +### NFCManager.make_string_from_payload(payload, tnf, type) +The make_string_from_payload method creates a string from the payload of an NFC tag message record (NdefRecord). -## Example of NFC API using +#### Returns -You can find complete example of using NFC API in [Rhodes-System-Api-Samples](http://github.com/rhomobile/rhodes-system-api-samples). See NFC Demo page - [NFC Demo](http://github.com/rhomobile/rhodes-system-api-samples/tree/master/app/Nfc/). +A string containing the payload of an NFC tag message record. +#### Parameters + * payload - a byte array containing the payload. + * tnf - int. The Type Name Format. From NdefRecord. + * type - Array of bytes. The payload type. From NdefRecord. + +### NFCManager.make_payload_with_absolute_uri(uri_string) + +The make_payload_with_absolute_uri method prepares a byte array for an NFC record payload from a string with an absolute URI. + +#### Returns + +A byte array for an NFC record payload. + +#### Parameters + +uri_string - a string containing an absolute URI. + +#### Example + + :::ruby + payload = Rho::NFCManager.make_payload_with_absolute_uri('http://www.rhomobile.com') + +### NFCManager.make_payload_with_well_known_uri(prefix_code, uri_string) + +The make_payload_with_absolute_uri method prepares a byte array for an NFC record payload from a string with an absolute URI. + +#### Returns + +A byte array for an NFC record payload. + +#### Parameters + + * prefix_code - an int containing a prefix code. + * uri_string - a string containing an absolute URI. + +#### Example + + :::ruby + def do_p2p_enable + # prepare an NdefMessage for sending to another device + payload = Rho::NFCManager.make_payload_with_well_known_uri(0, 'http://www.rhomobile.com') + # Create a hash -- id, tnf, type, payload -- for an NFC record + hash = { 'id' => [0], 'type' => Rho::NdefRecord::RTD_URI, 'tnf' => Rho::NdefRecord::TNF_WELL_KNOWN, 'payload' => payload} + # Create the NFC record with that hash + record = Rho::NFCManager.make_NdefRecord_from_hash(hash) + records = [record] + # Create the NdefMessage from the NdefRecord (just one record in array) + msg = Rho::NFCManager.make_NdefMessage_from_array_of_NdefRecord(records) + # start push message + Rho::NFCManager.p2p_enable_foreground_nde_push(msg) + add_to_log('Enable PUSH P2P') + set_log($log) + end + +### NFCManager.make_payload_with_well_known_text(language, text) + +The make_payload_with_well_known_text method prepares a byte array for an NFC record payload from a string language code and a string text. + +#### Returns + +A byte array for an NFC record payload. + +#### Parameters + + * language - a string containing a language code. + * text - a string containing an absolute URI. \ No newline at end of file