The Card Reader module decodes the card data when read through a card reader attachment. Currently this is available only on Symbol Technologies devices.Only the foreground application is given access to the card reader hardware, when an application is sent to the background its state will be saved and it will automatically relinquish control of the card reader. When brought back to the foreground, an application previously using the card reader will have its previous configuration (eg. pinTimeout) reapplied to the card reader automatically.
In order to use this API you must include the following extension in your build.yml
.
:::ruby
extensions: [“cardreader”]
The cardreader
extension is also included automatically if you specify the following in your build.yml
.
:::ruby
app_type: “rhoelements”
If you are building a Windows Mobile or Windows CE app with this API, you must set your app_type as “rhoelements” in your build.yml as shown here. |
Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.
Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.
Closes the card reader.
Synchronous Return:
Method Access:
myObject.close()
Rho.CardReader.close()
Rho::CardReader.close()
This method will return all of object/value pairs for the propertyNames of the API class.
Parameters
Async Callback Returning Parameters: HASH
Synchronous Return:
Map of all available properties
: this method also supports async callbacks - check the Callback tab for callback return parameters.
Method Access:
myObject.getAllProperties(CallBackHandler callback)
Rho.CardReader.getAllProperties(CallBackHandler callback)
Rho::CardReader.getAllProperties(CallBackHandler callback)
This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.
Synchronous Return:
Default object of Module.
Method Access:
Rho.CardReader.getDefault()
Rho::CardReader.getDefault()
This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.
Parameters
List of properties I want to know about
Async Callback Returning Parameters: HASH
Synchronous Return:
Map of properties I want to know about
: this method also supports async callbacks - check the Callback tab for callback return parameters.
Method Access:
myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
Rho.CardReader.getProperties(ARRAY arrayofNames, CallBackHandler callback)
Rho::CardReader.getProperties(ARRAY arrayofNames, CallBackHandler callback)
This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.
Parameters
The property to return info about.
Async Callback Returning Parameters: STRING
Synchronous Return:
The property to return info about.
: this method also supports async callbacks - check the Callback tab for callback return parameters.Method Access:
myObject.getProperty(STRING propertyName, CallBackHandler callback)
Rho.CardReader.getProperty(STRING propertyName, CallBackHandler callback)
Rho::CardReader.getProperty(STRING propertyName, CallBackHandler callback)
Opens the card reader.
Parameters
Async Callback Returning Parameters: HASH
Data read by the card reader. This may be card data, the PAN data extracted from the card data, encrypted PIN block data, or a message. In case of an ISO/ABA card [eg: a financial card], data is encrypted. For other cards, data is in the clear.
Describes the data. This will be either: ‘CR’,‘ENCDATA’,‘PAN’, or ‘MESSAGE’. This equates to card data, encrypted PIN block data, PAN data, or a message, respectively.
This provides the information regarding the card reader head configuration. Available only on Android.
This is the raw data read by the card reader from all the tracks. Available only on Android and the value is in HEX format.
The track1 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track1Status value returned is true.
The track2 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track2Status value returned is true.
The track3 clear/masked data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track3Status value returned is true.
The status of the track1 clear/masked data read by the card reader. Available only on Android.
The status of the track2 clear/masked data read by the card reader. Available only on Android.
The status of the track3 clear/masked data read by the card reader. Available only on Android.
The track1 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track1EncryptedStatus value returned is true.
The track2 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track2EncryptedStatus value returned is true.
The track3 encrypted data read by the card reader. Available only on Android and the value is in HEX format. This value should be used only when the track3EncryptedStatus value returned is true.
The status of the track1 encrypted data read by the card reader. Available only on Android.
The status of the track2 encrypted data read by the card reader. Available only on Android.
The status of the track3 encrypted data read by the card reader. Available only on Android.
The encrypted KSN serial number read by the card reader. Available only on Android. The value is in HEX format.
Synchronous Return:
Method Access:
myObject.open(CallBackHandler callback)
Rho.CardReader.open(CallBackHandler callback)
Rho::CardReader.open(CallBackHandler callback)
This method allows you to set the attributes of the default object instance by passing in an object of the same class.
Parameters
An instance object that is of the same class.
Synchronous Return:
Method Access:
Rho.CardReader.setDefault(SELF_INSTANCE: Rho::CardReader defaultInstance)
Rho::CardReader.setDefault(SELF_INSTANCE: Rho::CardReader defaultInstance)
This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.
Parameters
Map of properties I want to set
Synchronous Return:
Method Access:
myObject.setProperties(HASH propertyMap)
Rho.CardReader.setProperties(HASH propertyMap)
Rho::CardReader.setProperties(HASH propertyMap)
This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.
Parameters
The one property name that I want to set
The one property value that I want to set
Synchronous Return:
Method Access:
myObject.setProperty(STRING propertyName, STRING propertyValue)
Rho.CardReader.setProperty(STRING propertyName, STRING propertyValue)
Rho::CardReader.setProperty(STRING propertyName, STRING propertyValue)
When enabled, appends a carriage return to any data returned as keystrokes by the cardreader. This is useful for auto submitting returned data without extra interaction necessary.
Default: false
Property Access:
myObject.autoEnter
Rho.CardReader.autoEnter
Rho::CardReader.autoEnter
When enabled, appends a tab to any data returned as keystrokes by the cardreader. This is useful when filling out a form so that you can move to the next field without extra interaction necessary.
Default: false
Property Access:
myObject.autoTab
Rho.CardReader.autoTab
Rho::CardReader.autoTab
This method is present to provide backwards compatibility with PocketBrowser code, devices supported by RhoElements will have a single card reader driver installed as part of the platform. If the device has multiple card reader drivers installed this parameter is used to select which driver to use. The drivers present are output in the log file when the card reader is initialized. This parameter is also used to distinguish between an MSR and a DCR, e.g. if you attach a DCR7000 to your device you can specify that only the MSR functionality is used by specifying this parameter as ‘MSR7000’.
Possible Values (STRING):
MSR9000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.
MSR9001 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.
MSR9500 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.
MSRCAMEO drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRCAMEO.DLL.
MSR7000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.
DCR7000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.
MSR55 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC55.DLL.
MSR3000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.
Property Access:
myObject.moduleName
Rho.CardReader.moduleName
Rho::CardReader.moduleName
Sets the card data without the need of a swipe. This accepts any 16 digit number as the string value. Ensure that pinEntry is true before getting the property of panData.
(Only compatible with DCR7000-x00)
Property Access:
myObject.panData
Rho.CardReader.panData
Rho::CardReader.panData
Turns the PIN entry on or off.
(Only compatible with DCR7000-x00)
Property Access:
myObject.pinEntry
Rho.CardReader.pinEntry
Rho::CardReader.pinEntry
PIN entry timeout in milliseconds. A value of 65535 sets the timeout to infinite. Accepts values between 0 and 65535.
(Only compatible with DCR7000-x00)
Default: 30000
Property Access:
myObject.pinTimeout
Rho.CardReader.pinTimeout
Rho::CardReader.pinTimeout
The default card reader on the device is enabled when the index view is loaded. When a card is swiped the swipeEvent is called.
#/app/Model def index Rho::CardReader.open(url_for(:action => :myswipeevent)) end def myswipeevent puts "Swipe params: #{@params}" puts "Mode is #{@params['mode']}" puts "Data is #{@params['data']}" end
Enable card reader and receive a callback when a card is swiped.
function cardreader_callback(params) { alert("Received data from card reader: "+params["data"]); } function connect() { Rho.CardReader.open(cardreader_callback); }
def connect Rho::CardReader.open(url_for(:action => :cardreader_callback)) redirect :index end def cardreader_callback Alert.show_popup("Received card reader data: #{@params[:data]}") end
There are two ways to use the card reader. One is to receive a callback when a card is swiped, the other is to have it simulate keypresses. See below for an example of this second option.
// Configure the MSR to output keystrokes instead of calling a function when a card is swiped // Note the absence of a callback parameter // Also, After emitting the keystrokes, automatically send a "Tab" keypress Rho.CardReader.autoTab = true; Rho.CardReader.open(); Rho.CardReader.autoEnter = true; Rho.CardReader.open();
# Configure the MSR to output keystrokes instead of calling a function when a card is swiped # Note the absence of a callback parameter # Also, After emitting the keystrokes, automatically send a "Tab" keypress Rho::CardReader.autoTab = true Rho::CardReader.open() # Instead of "Tab", we could request a simulated "Enter" Rho::CardReader.autoEnter = true Rho::CardReader.open()
If the CardReader open method is not specified with a callback, the cardreader data will be returned as keystrokes. If both the autotab and autoenter parameters are set to “enabled”, autoenter will take precedence. An opened card reader must be closed before the attached card reader device and associated modulename parameter are changed. Any attempt to set a parameter to an invalid value, will result in no effect on the parameter’s current value. There should be made a delay around 2 secs or more between API calls which interact with hardware.
For the DCR7000 the ModuleName parameter must be set at least once before the readevent parameter is set. If the card reader is an MSR, when a card is swiped it returns the data read from the card. Setting ModuleName to a DCR will cause the card data to be returned followed by the PAN Data before waiting for a PIN to be entered on the keypad. Once entered the PIN will be encrypted and returned by a third ReadEvent. The card must be a validly formatted IATA or ABA card.
There is no way to abort a pending PIN entry (other than the customer pressing the Cancel button), for security reasons. Therefore if the reader is closed or RhoElements is quit during that time it will become unresponsive until a PIN is entered or the PIN timeout occurs.
In certain circumstances it is possible that the card reader may return empty card data. The JavaScript event function should be able to handle this correctly.
Applications running in RhoElements should be resilient against the card reader being detached and subsequently reattached. Card data parsing code should be robust against unexpected characters in the first read after reattachment.
The encrypted data is supported only on the card readers that are configured for encryption. Since the encrypted data might contain unreadable characters sometimes it is recommended to use only JSON object method rather than JavaScript ‘%s’ notation.