CardReader Meta Tag

PocketBrowser 3.x API

The CardReader Meta Tag is a retrieval tag that either navigates to a URL or calls a JavaScript function when an attached card reader decodes some data.

CardReader (META Tag) Syntax
<META HTTP-Equiv="cardreader" content="parameter:value">

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description
Default Value
Open Opens the card reader. Resets the ReadEvent to "". Closed
Close Closes the card reader Closed
Copy methods template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description
Default Value
PINTimeout:[Value] 0 - 65535 PIN entry timeout in milliseconds. A value of 65535 sets the timeout to infinite. 30000->30s timeout
PINEntry:[Value] On, Off Turns the PIN entry on or off. OFF
PANData:[Value] Any 16 digit string Sets the card data without the need of a swipe. Invoked only. Empty String
AutoTab:[Value] Enabled, Disabled When enabled, appends a tab to any data returned as keystrokes by the cardreader. "disabled"
AutoEnter:[Value] Enabled, Disabled When enabled, appends a carriage return to any data returned as keystrokes by the cardreader. "disabled"
ModuleName:[Value] MSR9000, MSR9001, MSR9500, MSRCAMEO, MSR7000, DCR7000, MSR55, MSR3000 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 initialised. 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' None
Copy parameters template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Modules return information back to their web pages via retrieval tags, for example the scanner has a retrieval tag called 'DecodeEvent' which is called whenever it decodes a barcode. To register to receive a retrieval tag call the module as follows:

<META HTTP-Equiv="[Module]" content="[RetrievalTag]:url('[URI]')">
So to register to retrieve the Scanner's DecodeEvent the following syntax would be used:
<META HTTP-Equiv="Scanner" content="DecodeEvent:url('Javascript:doScan('%6', '%s', %3, '%2');')">

Retrieval tags return information by replacing the text in place holders, defined as '%s' or '%<number>'. Each place holder represents 1 return value with '%s' being populated sequentially or '%<number>' providing direct acces to the desired value.

If the content for the Scanner's DecodeEvent is:

"url('Javascript:doScan('%6', '%s', %3, '%2');')"

The function would be called as follows:
"Javascript:doScan('Decode', '5449000053879', 0x35, 'SCN:EAN13');"


ReadEvent
ReadEvent:URL('URI') URI is either a URL or a javascript function. If a URL, the browser navigates to the URL when the attached card reader decodes some data. If a javascript function, the function is treated as a callback which is invoked when the card reader decodes data. Issuing this tag, automatically opens the card reader, if it has not been opened already.

ID Name Description
1 Data 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.
2 Mode 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.
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript



The following example sets up the card reader to submit the scanned data to an asp page upon successful decoding

<META HTTP-Equiv="cardreader" Content="readevent:url('http://mypage.asp?Data=%s;Mode=%s')">
Copy example to clipboard Copy example to clipboard

The following example sets up the card reader to call a javascript function upon successful decoding. The javascript function will be called 3 times, once with the raw card data, once with just the pan data extracted from the raw card data, and once with the encrypted pan data if the pin has been supplied by the user within 10s.:

<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>PB 3.0 CardReader Test</title>
<META HTTP-Equiv="CardReader" Content="PINEntry:ON">
<META HTTP-Equiv="CardReader" Content="PINTimeout:0x2710">
<META HTTP-Equiv="CardReader" Content="ReadEvent:url('javascript:doTransaction('%s', '%s');')">

<script language="javascript" type="text/javascript">
var Generic = new ActiveXObject("PocketBrowser.Generic");
function doTransaction(data, mode)
{
switch(mode) {
case 'CR':
alert('Card: '+data);
break;
case 'ENCDATA':
alert('Encoded data: '+data);
break;
case 'MESSAGE':
alert('Error: '+data);
break;
case 'PAN':
alert('PAN data: '+data);
alert('Please turn the unit over and enter the PIN');
break;
}
}
</script>
</head>
<body>
</body>
</html>
Copy example to clipboard Copy example to clipboard

The following example closes the card reader

<META HTTP-Equiv="CardReader" Content="Close">
Copy example to clipboard Copy example to clipboard
General
If the CardReader return URI is "", the cardreader data will be returned as keystrokes. The readevent parameter must be set at least once before the pandata parameter is set. 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.

AutoEnter and AccelerateKey
The AccelerateKey Meta tag controls the behaviour of Accelerate keys on Windows CE, if the Enter key is configured to be non functional then AutoEnter will also appear to not function either

Operational Modes
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.

Event URI and Parameter Persistence
The ReadEvent URI, the PINTimeout, PINEntry, AutoEnter / AutoTab parameters are page-specific values. When PocketBrowser performs a page navigate (not a JavaScript callback), the URI is invalidated, the parameters set to their default values and the cardreader is closed. While the cardreader is open, the URI value may be changed via passing a new readevent parameter/value pair. In the case that the CardReader is already open, the readevent parameter will simply update the URI and do nothing to the state of the port.

Invalid parameter values
Any attempt to set a parameter to an invalid value, will result in no effect on the parameter's current value.

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 PocketBrowser 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 PocketBrowser should be resiliant 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.


Supported Platforms Windows CE, Windows Mobile, Windows Mobile SE
Persistence See Comment Above
Min. Requirements You must have the appropriate drivers installed on your device to use the CardReader. You will see which drivers are installed in the PocketBrowser log file after you attempt to use any of the card reader functions in PocketBrowser. If you wish to install drivers they can be downloaded from http://support.symbol.com, an example search would be MSR3000 or DCR7x00. Take note that different drivers are required for the DCR7000-100 and DCR7000-200.