Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

CardReader

Methods10
Methods - Class
enumerategetDefaultsetDefault
Methods - Instance
closegetAllPropertiesgetPropertiesgetPropertyopensetPropertiessetProperty
Properties6
Instance Properties
autoEnterautoTabmoduleNamepanDatapinEntrypinTimeout
Examples3
Basic ExampleConnect to card readerSet card reader properties
Remarks6
GeneralOperational Modes (Backwards compatibility with PocketBrowser)Closing the reader while PIN entry pendingBlank card dataDetaching / Reattaching the Card ReaderEncrypted Card data

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.

Enabling the API

In order to use this API you must include the following extension in your build.yml.

extensions: ["cardreader"]

The cardreader extension is also included automatically if you specify the following in your build.yml.

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.

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

close
()

Closes the card reader.

Synchronous Return:

  • Void

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.close()
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.CardReader.close()
    • Ruby: Rho::CardReader.close()
enumerate
(CallBackHandler callback)
getAllProperties
(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of all available properties

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getAllProperties(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.CardReader.getAllProperties(CallBackHandler callback)
    • Ruby: Rho::CardReader.getAllProperties(CallBackHandler callback)
getDefault
()

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:

  • SELF_INSTANCE :

    Default object of Module.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.CardReader.getDefault()
    • Ruby: Rho::CardReader.getDefault()
getProperties
(ARRAY arrayofNames, CallBackHandler callback)

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

  • arrayofNames : ARRAY

    List of properties I want to know about

    • Object : STRING

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of properties I want to know about

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.CardReader.getProperties(ARRAY arrayofNames, CallBackHandler callback)
    • Ruby: Rho::CardReader.getProperties(ARRAY arrayofNames, CallBackHandler callback)
getProperty
(STRING propertyName, 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

  • propertyName : STRING

    The property to return info about.

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

    Synchronous Return:

    • STRING :

      The property to return info about.

      : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getProperty(STRING propertyName, CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.getProperty(STRING propertyName, CallBackHandler callback)
      • Ruby: Rho::CardReader.getProperty(STRING propertyName, CallBackHandler callback)
    open
    (CallBackHandler callback)

    Opens the card reader.

    Parameters

    • callback : CallBackHandler Optional

    Async Callback Returning Parameters: HASH

      • data : STRING

        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.

      • mode : STRING

        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.

      • encryption : BOOLEAN

        This provides the information regarding the card reader head configuration. Available only on Android.

      • rawData : STRING

        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.

      • track1 : STRING

        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.

      • track2 : STRING

        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.

      • track3 : STRING

        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.

      • track1Status : BOOLEAN

        The status of the track1 clear/masked data read by the card reader. Available only on Android.

      • track2Status : BOOLEAN

        The status of the track2 clear/masked data read by the card reader. Available only on Android.

      • track3Status : BOOLEAN

        The status of the track3 clear/masked data read by the card reader. Available only on Android.

      • track1Encrypted : STRING

        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.

      • track2Encrypted : STRING

        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.

      • track3Encrypted : STRING

        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.

      • track1EncryptedStatus : BOOLEAN

        The status of the track1 encrypted data read by the card reader. Available only on Android.

      • track2EncryptedStatus : BOOLEAN

        The status of the track2 encrypted data read by the card reader. Available only on Android.

      • track3EncryptedStatus : BOOLEAN

        The status of the track3 encrypted data read by the card reader. Available only on Android.

      • ksn : STRING

        The encrypted KSN serial number read by the card reader. Available only on Android. The value is in HEX format.

    Synchronous Return:

    • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.open(CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.open(CallBackHandler callback)
      • Ruby: Rho::CardReader.open(CallBackHandler callback)
    setDefault
    (SELF_INSTANCE: Rho::CardReader defaultInstance)

    This method allows you to set the attributes of the default object instance by passing in an object of the same class.

    Parameters

    • defaultInstance : SELF_INSTANCE: Rho::CardReader

      An instance object that is of the same class.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.CardReader.setDefault(SELF_INSTANCE: Rho::CardReader defaultInstance)
      • Ruby: Rho::CardReader.setDefault(SELF_INSTANCE: Rho::CardReader defaultInstance)
    setProperties
    (HASH propertyMap)

    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

    • propertyMap : HASH

      Map of properties I want to set

      • Object : STRING

    Synchronous Return:

    • Void

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.setProperties(HASH propertyMap)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.setProperties(HASH propertyMap)
      • Ruby: Rho::CardReader.setProperties(HASH propertyMap)
    setProperty
    (STRING propertyName, STRING propertyValue)

    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

    • propertyName : STRING

      The one property name that I want to set

    • propertyValue : STRING

      The one property value that I want to set

    Synchronous Return:

    • Void

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.setProperty(STRING propertyName, STRING propertyValue)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.setProperty(STRING propertyName, STRING propertyValue)
      • Ruby: Rho::CardReader.setProperty(STRING propertyName, STRING propertyValue)

    Properties

    autoEnter
    : BOOLEAN

    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:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.autoEnter
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.autoEnter
      • Ruby: Rho::CardReader.autoEnter
    autoTab
    : BOOLEAN

    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:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.autoTab
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.autoTab
      • Ruby: Rho::CardReader.autoTab
    moduleName
    : STRING
    Deprecated

    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):

    Constant: Rho.CardReader.MSR9000 (For Ruby use "::" for all "." when referencing constants)
    String: msr9000

    MSR9000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.

    Constant: Rho.CardReader.MSR9001 (For Ruby use "::" for all "." when referencing constants)
    String: msr9001

    MSR9001 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.

    Constant: Rho.CardReader.MSR9500 (For Ruby use "::" for all "." when referencing constants)
    String: msr9500

    MSR9500 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.

    Constant: Rho.CardReader.MSRCAMEO (For Ruby use "::" for all "." when referencing constants)
    String: msrcameo

    MSRCAMEO drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRCAMEO.DLL.

    Constant: Rho.CardReader.MSR7000 (For Ruby use "::" for all "." when referencing constants)
    String: msr7000

    MSR7000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.

    Constant: Rho.CardReader.DCR7000 (For Ruby use "::" for all "." when referencing constants)
    String: dcr7000

    DCR7000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC50.DLL.

    Constant: Rho.CardReader.MSR55 (For Ruby use "::" for all "." when referencing constants)
    String: msr55

    MSR55 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSRMC55.DLL.

    Constant: Rho.CardReader.MSR3000 (For Ruby use "::" for all "." when referencing constants)
    String: msr3000

    MSR3000 drivers. Return value while getting the property of moduleName will be its associated DLL name i.e. MSR3000.DLL.

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.moduleName
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.moduleName
      • Ruby: Rho::CardReader.moduleName
    panData
    : STRING

    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:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.panData
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.panData
      • Ruby: Rho::CardReader.panData
    pinEntry
    : BOOLEAN

    Turns the PIN entry on or off.

    (Only compatible with DCR7000-x00)

    Property Access:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.pinEntry
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.pinEntry
      • Ruby: Rho::CardReader.pinEntry
    pinTimeout
    : INTEGER

    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:

    • Instance: This property can be accessed via an instance object of this class:
      • myObject.pinTimeout
    • Default Instance: This property can be accessed via the default instance object of this class.
      • JavaScript: Rho.CardReader.pinTimeout
      • Ruby: Rho::CardReader.pinTimeout

    Examples

    Basic Example

    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
    Connect to card reader

    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
    Set card reader properties

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

    Remarks

    General

    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.

    Operational Modes (Backwards compatibility with PocketBrowser)

    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.

    Closing the reader while PIN entry pending

    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.

    Blank card data

    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.

    Detaching / Reattaching the Card Reader

    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.

    Encrypted Card data

    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.