USER MANUAL

SecureMag
Encrypted Magstripe Reader
OPOS Reference Guide

80096503-001
Rev E. 3/10/14

ID Technologies, Inc.
10721 Walker Street, Cypress CA 90630 Voice: (714) 761-6368 Fax: (714) 761-8880

SecureMag OPOS User Manual

Revision History
Revision

Date

Description

By

10/07/2009

Initial Release

JW

12/27/2010

Revised for Service Object Version: 1.13.302, Dll File

JW

Version: 3.0.2, and Control Object Version:1.13.001

1/31/2011

Added USB Keyboard and PS2 keyboard interface

support

JW

1/18/2012

OPOS driver for PS2 and USBKB v3.07 released.

Used keyboard driver name is MSR Keyboard Base
Driver.
(1) Add a special flag OutputDataConversion in
registry, and while the value is
STANDARD_MODE, then standard
BinaryConvertion property is used. Otherwise,
the DEFAULT _MODE output format will be
transmitted from SO. For compatibility reason,
the default value of flag is
DEFAULT_MODE. This Manual is the
DEFAULT _MODE description.
If AccountNumber in encrypted card data include
space, can be deal. The length of AccountNumber in
track1 is 12 21. And it in track2 is 12-19.

JW

3/10/2014

Add Windows 8.1 note

Add special setting
Add silent installation

CH

SecureMag OPOS User Manual

Table of Contents
1.
2.
2.1.
2.2.
2.3.
3.
3.1.
3.2.
3.3.
4.

Description ................................................................................................................................ 6
Methods, Properties and Events of SecureMag ........................................................................ 8
Methods of MSR .................................................................................................................. 8
Properties of MSR .............................................................................................................. 13
Events of MSR ................................................................................................................... 24
Programming Examples .......................................................................................................... 26
Visual C++ 6.0 Programming Example .............................................................................. 26
Visual Basic 6.0 Programming Example ............................................................................ 28
Visual Studio 2005/2008 C# Programming Example ......................................................... 31
Result Code/Error Code List ................................................................................................... 34

SecureMag OPOS User Manual

ID TECH SOFTWARE COPYRIGHT NOTICE

Copyright 2010 International Technologies & Systems Corporation. All rights
reserved. ID TECH is a registered trademark of International Technologies & Systems
Corporation. Value through Innovation, Spectrum is trademarks of International
Technologies & Systems Corporation.
ID TECH SOFTWARE LICENSE AGREEMENT
ID TECH ("LICENSOR") IS WILLING TO LICENSE THIS SOFTWARE TO YOU
ONLY IF YOU ACCEPT ALL OF THE TERMS IN THIS LICENSE AGREEMENT.
PLEASE READ THE TERMS CAREFULLY BEFORE YOU AGREE BECAUSE
YOU WILL BE BOUND BY THE TERMS OF THIS AGREEMENT. IF YOU DO
NOT AGREE TO THESE TERMS, LICENSOR WILL NOT LICENSE THIS
SOFTWARE TO YOU.
Ownership of the Software
1. The Licensor software program ("Software") and any accompanying written
materials are owned by Licensor [or its suppliers] and are protected by United States
copyright laws, by laws of other nations, and by international treaties.
Grant Of License
2. Licensor grants to you the right to use the Software in conjunction with an ID
TECH product. You may load one copy into permanent memory of one computer and
may use that copy only on that same computer.
Restrictions on Use and Transfer
3. You may not copy the Software, except that (1) you may make one copy of the
Software solely for backup or archival purposes, and (2) you may transfer the
Software to a single hard disk provided you keep the original solely for backup or
archival purposes. You may not copy the written materials.
4. You may permanently transfer the Software and any accompanying written
materials (including the most recent update and all prior versions) if you retain no
copies and the transferee agrees to be bound by the terms of this Agreement. Such a
transfer terminates your license. You may not rent or lease the Software or otherwise
transfer or assign the right to use the Software, except as stated in this paragraph.
5. You may not reverse engineer, decompile, or disassemble the Software.
Limited Warranty
4

SecureMag OPOS User Manual

6. If used in conjunction with an ID TECH product, Licensor warrants that the

Software will perform substantially in accordance with the accompanying written
materials for a period of 90 days from the date of your receipt of the Software. Any
implied warranties on the Software are limited to 90 days. Some states and territories
do not allow limitations on duration of an implied warranty, so the above limitation
may not apply to you.
7. LICENSOR DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
NON-INFRINGEMENT, WITH RESPECT TO THE SOFTWARE AND ANY
ACCOMPANYING WRITTEN MATERIALS. This limited warranty gives you
specific legal rights. You may have others, which vary from state to state.
8. LICENSOR'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY
SHALL BE REPLACEMENT OF THE SOFTWARE THAT DOES NOT MEET
LICENSOR'S LIMITED WARRANTY. Any replacement Software will be warranted
for the remainder of the original warranty period or 30 days, whichever is longer.
9. This Limited Warranty is void if failure of the Software has resulted from
modification, accident, abuse, or misapplication.
10. IN NO EVENT WILL LICENSOR BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY LOSS OF PROFITS, LOST SAVINGS, OR OTHER
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF YOUR USE
OR INABILITY TO USE THE SOFTWARE. Because some states do not allow the
exclusion or limitation of liability for consequential or incidental damages, the above
limitation may not apply to you.
11. This Agreement is governed by the laws of the state of California.
12. If you have any questions concerning this Agreement or wish to contact Licensor
for any reason, please write: ID TECH, 10721 Walker Street, Cypress, CA 90630 or
call (714) 761-6368.
13. U.S. Government Restricted Rights. The Software and documentation are
provided with Restricted Rights. Use, duplication, or disclosure by the Government is
subject to restrictions set forth in subparagraph (c)(1) of The Rights in Technical Data
and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1)(ii)
and (2) of Commercial Computer Software - Restricted Rights at 48 CFR 52.227-19,
as applicable. Supplier is ID TECH, 10721 Walker Street, Cypress, CA 90630.

SecureMag OPOS User Manual

1. Description
The documentation describes the properties, methods, and events of the ID TECH
SecureMag MSR OPOS component. The component includes two parts: a Control
Object running on the upper level, which is an ActiveX control, and a Service Control
running on the lower level, which is an OLE automation server. The properties,
methods, and events are exposed by the Control Object. When the Control Object is
imported into your project as an ActiveX control, you will see all the properties,
methods, and events.
For different interface devices, OPOS drivers may be different. For PS/2 keyboard or
USB HID Keyboard interfaces device, the standard keyboard should not be pressed
when swiping cards, otherwise the card data will be wrong , MSR OPOS Driver will
display a warning dialog and the data will be discarded.
The USB HID Keyboard interfaces device cant support hot plug when OPOS driver
is in the Open state. If you have already pulled out the device in Open state, close
driver and reopen can use again.
For keyboard interface MSR device, the OPOS supports only one keyboard MSR
device (one PS2 device or one USBKB device) for use on a computer. In other words:
at the same time, the OPOS only allows to connect one keyboard MSR device.
In Windows8.1, you should connect the device with PC before you run setup.exe.
Once you plug the device into another port, you should run DriverRollback.bat as
administrator which you can find in xxxx\ID TECH\MagSwipe\USB HID OPOS
MagSwipe Driver, xxxx means the program installation directory. Usually the
directory is C:\Program files\ID TECH\MagSwipe\USB HID OPOS MagSwipe
Driver
2. Special Settings
There is some special setting regarding customer request that change the action of OPOS.
1. Registry Settings:
[HKEY_LOCAL_MACHINE\Software\OLEforRetail\ServiceOPOS\MSR\IDTECH_SECUREMAG_USBHID]
@="IDTechMMII.USBHID"
DebugOnOff=dword:00000000

Registry description:
DebugOnOff = dword:0

0 debug off, 1 debug on

3. Target Device:
ID TECH SecureMag
RS232, USB-CDC, USB-HID, USB-KB, PS/2 KB interface
6

SecureMag OPOS User Manual

Platform:
Microsoft Windows 8.1 32bit, Windows 8 32bit, Windows 7 32bit,Vista 32bit, XP 32bit,
Microsoft Windows 8.1 64bit, Windows 8 64bit, Windows 7 64bit,Vista 64bit.
Service Object and Control Object:
Control Object Version:1.13.001

4. Silent Install:
Copy the silent install script to the directory of setup.exe file. Open a command promote windows
and change to the directory of setup.exe file:
Install: setup.exe /s /f1./setup.iss.install, or
Install: setup.exe /s /f1./setup.iss.install_x64 for 64bit OS,
Restart OS.
Uninstall: setup.exe /s /f1./setup.iss.uninstall, restart OS.
Note: There should not be any other software installed with MSR Keyboard filter driver, when to
use silent install script.

SecureMag OPOS User Manual

5. Methods, Properties and Events of SecureMag

This section describes methods, properties and events for the SecureMag Encrypted
MSR.
5.1. Methods of MSR
These function declarations may be different when the Control Object
(OPOSMSR.OCX) is imported into your application project. Please refer to the
UnifiedPOS Specification for more detailed information on the Control Object.
1) Open
Syntax
Remarks

LONG Open (BSTR DeviceName);

Call to open a device for subsequent I/O.
Device Name:
RS232 interface
USBCDC interface
USBHID interface
USBKB interface
PS/2 KB interface

IDTECH_SECUREMAG_RS232
IDTECH_ SECUREMAG _USBCDC
IDTECH_ SECUREMAG _USBHID
IDTECH_ SECUREMAG _USBKB
IDTECH_ SECUREMAG _PS/2KB

Support?
Yes
This method finds more parameters in the Windows Register Tables on key or
subkeys.
RS232 interface:
HKEY_LOCAL_MACHINE\Software\OLEforRetail\ServiceOPOS\MSR\
IDTECH_ SECUREMAG_RS232
Subkey: Connector
Key value name: COM1
Key value: "serialconn.dll"
Key value name: CONNECTOR
Key value: "COM1/baud=9600/parity=N/data=8/stop=1"
COM1 specify the serial port name, if the device is plugged in the second port, it
should be modified as "COM2".
USBCDC interface:
HKEY_LOCAL_MACHINE\Software\OLEforRetail\ServiceOPOS\MSR\
IDTECH_ SECUREMAG _USBCDC
Subkey: Connector
Key value name: CONNECTOR
Key value: "COM3/baud=9600/parity=N/data=8/stop=1"
8

SecureMag OPOS User Manual

COM3 specify the serial port name, if the device is plugged in the second port, it
should modified as "COM2". The rest settings should be right defined according
to the settings of the reader.
Key value Name: COM3, this name should be same the first field of
CONNECTOR key value. The field is separated by "/". So, if the reader is
changed to other port, this key value is needed modified also.
USBHID interface:
HKEY_LOCAL_MACHINE\Software\OLEforRetail\ServiceOPOS\MSR\
IDTECH_ SECUREMAG _USBHID
Subkey: Connector
Key value name: USBHID
Key value: "usbhidConn.dll"
Key value name: CONNECTOR
Key value: "USBHID/0acd/2010"
USB HID KB interface:
HKEY_LOCAL_MACHINE\Software\OLEforRetail\ServiceOPOS\MSR\
IDTECH_ SECUREMAG _USBKB
Subkey: Connector:
Key value name: CONNECTOR
Key value: USBKB/0acd/2030
First field USBHID specify the type of the connector. 0acd is the USB device
vendor ID, 2030 is the reader product ID.
Key value name: USBKB
Key value: usbkbConnector.dll
PS2 KB interface:
HKEY_LOCAL_MACHINE\Software\OLEforRetail\ServiceOPOS\MSR\
IDTECH_ SECUREMAG _PS/2KB
Subkey: Connector:
Key value name: CONNECTOR
Key value: PS2
Key value name: PS2
Key value: PS2Conn.dll
2) ClaimDevice
Added in Release 1.5
Syntax
LONG ClaimDevice (LONG Timeout);
Remarks Call this method to request exclusive access to the device. Many devices
require an application to claim them before they can be used. Release 1.0 1.4 In
releases prior to 1.5, this method is named Claim.
9

SecureMag OPOS User Manual

Support?

Yes

3) CheckHealth
Syntax
LONG CheckHealth (LONG Level);
Remarks Called to test the state of a device.
Support? Yes
Description When select CH_INTERNAL, check the SO response, if not it tells that
there is something wrong with the device. CheckHealthText property will be Internal
HCheck: Successful
When select CH_EXTERNAL, SO will return the firmware version of the SecureMag
device, if reading the firmware version is successful. CheckHealthText property will
be External HCheck: Successful + firmware version information. If Not
Responding, CheckHealthText property will be External HCheck: Not Responding.
When select CH_INTERACTIVE , SO will display a dialog , which include firmware
version and swiping card . And it can display the Real data of the card, include Start
Sentinel and End Sentinel. CheckHealthText property will show External HCheck::
HCheck: Complete, after the dialog is closed.

4) ClearInput
Syntax
LONG ClearInput ();
Remarks Called to clear all device input that has been buffered.
Support? Yes
5) DirectIO
Syntax
LONG DirectIO (LONG Command, LONG* pData, BSTR* pString);
Remarks
Call to communicate directly with the Service Object.
Support? No
Description In the current, it implemented incompletely. We will improve it in the
next release.
6) ReleaseDevice
Added in Release 1.5
Syntax
LONG ReleaseDevice ();
Remarks Call this method to release exclusive access to the device.
Release 1.0 1.4
In releases prior to 1.5, this method is named Release.
Support? Yes
7) Close
Syntax
Remarks
Support?

LONG Close ();

Called to release the device and its resources.
Yes
10

SecureMag OPOS User Manual

8) ResetStatistics Added in Release 1.8

Syntax
LONG ResetStatistics(BSTR m_StatisticsBuffer);
Remarks Called to Resets the defined resettable statistics in a device to zero.
Support? No
9) RetrieveStatistics Added in Release 1.8
Syntax
LONG RetrieveStatistics(BSTR* m_pStatisticsBuffer);
Remarks Called to Retrieves the requested statistics from a device.
Support? No
10) UpdateStatistics Added in Release 1.8
Syntax
LONG UpdateStatistics(BSTR m_StatisticsBuffer);
Remarks Called to Updates the defined resettable statistics in a device.
Support? No
11) CompareFirmwareVersion
Syntax
LONG CompareFirmwareVersion(BSTR m_FirmwareFileName,
long* m_pResult);
Remarks Called to compare the firmware version with current firmware version of
the device
Support? No
12) UpdateFirmware
Syntax
LONG UpdateFirmware(BSTR m_FirmwareFileName);
Remarks Called to update current firmware.
Support? No
13) ClearInputProperties
Syntax
void ClearInputProperties();
Remarks Sets all data properties that were populated as a result of firing a
DataEvent or ErrorEvent back to their default values.
Support? Yes
14) WriteTracks
Syntax
long WriteTracks(LPCTSTR data, long timeout)
Remarks Sets all data properties that were populated as a result of firing a
DataEvent or ErrorEvent back to their default values.
Support? No
15) AuthenticateDevice
Syntax
long AuthenticateDevice (LPCTSTR response)
Remarks To authenticate a device, the application first calls the
retrieveDeviceAuthenticationData method to retrieve a challenge token
11

SecureMag OPOS User Manual

from the device. The application then typically passes this token to
another entity that has special knowledge of a shared secret and is able to
create a proper response token. This response token is then passed as the
response parameter to this method and the service uses it to validate the
authentication request. If this method succeeds, the device enters the
authenticated state and the service sets the DeviceAuthenticated property
to true.
For SecureMag:
The response needs to be 16 bytes in length. And it should be transmitted
as a Hex string. Example, 0xAB 0x00 0x09 is converted to "AB0009".
Support?
NO
Yes

------- SecureMag Firmware Version 3.24; MMII Device.

------- SecureMag Firmware Version Other.

16) DeauthenticateDevice
Syntax
long DeauthenticateDevice (LPCTSTR response)
Remarks This method is used to deauthenticate a device that is currently in the
authenticated state (DeviceAuthenticated = true). The token is typically
generated by passing the challenge retrieved from the
retrieveDeviceAuthenticationData method to an entity that has special
knowledge of a shared secret. If this method succeeds the service sets
DeviceAuthenticated to false and enqueues a StatusUpdateEvent with
status value set to MSR_SUE_DEVICE_DEAUTHENTICATED.
For SecureMag:
The response needs to be 16 bytes (when Encryption Algorithm is 3DES)
or 8 bytes (when Encryption Algorithm is AES) in length. And it should
be transmitted as a Hex string. Example, 0xAB 0x00 0x09 is converted
to "AB0009".
Support?
NO
Yes

------- SecureMag Firmware Version 3.24; MMII Device.

------- SecureMag Firmware Version Other.

17) RetrieveCardProperty
Syntax
long RetrieveCardProperty (BSTR Name, BSTR *Value)
Remarks Retrieves the value of specific parsed properties from the
last card swiped.
Support? Yes
12

SecureMag OPOS User Manual

18) RetrieveDeviceAuthenticationData
Syntax
long RetrieveDeviceAuthenticationData (LPCTSTR challenge)
Remarks Applications call this method to retrieve a challenge token that will
subsequently be used to generate response tokens that will be passed to
the authenticateDevice and deauthenticateDevice methods. The
challenge token is typically sent to another entity that has special
knowledge of a shared secret that is required to generate the proper
response token(s).
For SecureMag:
The challenge is always 26 bytes in length. And it will be transmitted as
a Hex string. Example, 0xAB 0x00 0x09 is converted to "AB0009".
Support?
NO
Yes

------- SecureMag Firmware Version 3.24; MMII Device.

------- SecureMag Firmware Version Other.

19) UpdateKey
Syntax
long UpdateKey (BSTR Key, BSTR KeyName)
Remarks Provides a new encryption key to the device. It is used only for those
encryption algorithms in which new key values are sent to the terminal
as a field in standard messages from the host.
For SecureMag:
KeyName can be set any value. The Key need be 80 bytes in length. And
it should be transmitted as a Hex string. Example, 0xAB 0x00 0x09 is
converted to "AB0009".
Support?
NO
Yes

------- MMII Device.

------- SecureMag Device.

5.2. Properties of MSR

Please refer to the UnifedPOS Specification for detailed information.
NOTE: CO --- Control Object
SO --- Service Object
AP or App --- the abbreviation of Application.

13

SecureMag OPOS User Manual

Property Group1---Description

Name

Type

Mutability

Use

Description

Support?

Identify the Control Object and

Yes

After
String

DeviceControlDescri

read-only

--

the company that produced it

ption
int32

DeviceControlVersio

read-only

--

hold the Control Object version

Yes

number.

n
DeviceServiceDescrip

String

read-only

open

identify the Service Object

Yes

supporting the device and the

tion

company that
produced it
DeviceServiceVersion

int32

read-only

open

hold the Service Object version

Yes

number.
PhysicalDeviceDescri

string

read-only

open

Yes

pertinent information about it.

ption
PhysicalDeviceName

identify the device and any

string

read-only

open

identify the device and any

Yes

pertinent information about it.

Property Group2---Control
Name

Type

Mutability

Use

Description

Support?

SecureMag must be claimed for

Yes

After
Claimed

Boolean

read-only

open

exclusive use before access its

methods and properties, and
before any events to be fired.

It

is initialized to FALSE by the

Open method. It is set to TRUE
after the method Claim is
successfully called.
AutoDisable

Boolean

read-write

open

When TRUE, as soon as an event

Yes

DataEvent is received, then

DeviceEnabled is automatically
to FALSE. It is initialized to
FALSE by the Open method.
DeviceEnabled

Boolean

read-write

open&

When FALSE, SecureMag has

claim

been disabled and any subsequent

input will be discarded (No
DataEvent could be received even
if the card is swiped). It is
initialized to FALSE by the Open

14

Yes

SecureMag OPOS User Manual

method.
FreezeEvents

boolean

read-write

open

When TRUE, events are not

Yes

required to be delivered and will

be held by SO until events are
unfrozen.

It is initialized to

FALSE by the Open method.

DataEventEnabled

boolean

read-write

open

When TRUE, a DataEvent or

Yes

ErrorEvent will be delivered

immediately when had. (Of
course , FreezeEvents=FALSE
and DeviceEnabled=TRUE is a
prerequisit).

It is initialized to

FALSE by the Open method.

CapPowerReportin

int32

read-only

open

Identifies the reporting

No

capabilities of the device about

Power. It seems that SecureMag

doesnt support in the hardware.
PowerNotify

int32

read-write

open

Contains the type power

No

notification selection made by the

Application.

is initialized to

OPOS_PN_DISABLED by the
Open method.
PowerState

int32

read-only

open

Contains the current power

condition.

No

It seems that

SecureMag doesnt support in the

hardware.
State

int32

Read-only

--

Contains the current state of the

Yes

Control. It can be set to one of the

four
Values: Closed, Idle, Busy, or
Error.
DataCount

int32

Read-only

open

Holds the number of enqueued

Yes

DataEvents remained in the

queue.
CheckHealthText

string

read-only

open

Holds the results of the most

recent call to the CheckHealth
method.

Before the first

CheckHealth method call, its

value is uninitialized.

15

Yes

SecureMag OPOS User Manual

Property Group3---Track Control
Name

Type

Mutability

Use

Description

Support?

If TRUE, SecureMag

Yes

After
CapISO

boolean

read-only

open

supports ISO cards.

CapJISOne

boolean

read-only

open

If TRUE, SecureMag

Yes

supports JIS Type-I

cards. JIS-I cards are a
superset of ISO cards.
Therefore, if
CapJISOne is true, it is
implied that CapISO is
also TRUE.
CapJISTwo

boolean

read-only

open

If TRUE, SecureMag

Yes

supports JIS type-II

cards.
CapTransmitSentinels

boolean

read-only

open

If TRUE, SecureMag is

Yes

able to transmit the start

and end sentinels. e.g.
start sentinel could be
% or ;, and stop
sentinel could be ?.
DecodeData

boolean

read-write

open

If TRUE, each byte of

Yes

track data properties is

mapped from its original
encoded bit sequence (as
it exists on the magnetic
card) to its
corresponding decoded
ASCII bit sequence.
ParseDecodeData

boolean

read-write

open

When TRUE, the

Yes

decoded data contained

within the Track1Data
and Track2Data
properties is further
separated into fields for
access via various other
properties.

If

DecodeData=FALSE,
ParseDecodeData must
be false.
TransmitSentinels

boolean

read-write

open

If TRUE, the
Track1Data,

16

Yes

SecureMag OPOS User Manual

Track2Data,
Track3Data, and
Track4Data properties
contain start and end
sentinel values.
Otherwise only the track
data between these
sentinels.
TracksToRead

int32

read-write

open

Indicate which track

Yes

data that the App wishes

to get following a card
sweep.
ErrorReportingType

int32

Read-write

open

Holds the type of errors

Yes

to report via
ErrorEvents. This
property has one of the
following values:
MSR_ERT_CARD or
MSF_ERT_TRACK

Property Group4---TrackData
Name

Type

Mutability

Use

Description

Support?

Holds the track 1 data

Yes

After
Track1Data

binary

read-only

open

obtained from the most

recently swept card.

If

DecodeData is true, then it

has been decoded from the
raw format. it may also be
parsed into other properties
when the ParseDecodeData
property is set.
Track1DiscretionaryD

binary

read-only

open

Holds the track 1

discretionary data obtained

ata

from the most recently swept

card.

It may be NULL

when:
1) The field was not included
in the track data obtained, or,
2) The track data format was
not supported, 3)

17

Yes

SecureMag OPOS User Manual

ParseDecodeData is false.
Track2Data

binary

read-only

open

Holds the track 2 data

Yes

obtained from the most

recently swept card.

If

DecodeData is true, then it

has been decoded from the
raw format. it may also be
parsed into other properties
when the ParseDecodeData
property is set.
Track2DiscretionaryD

binary

read-only

open

Holds the track 2

Yes

discretionary data obtained

ata

from the most recently swept

card.

It may be NULL

when:
1) The field was not included
in the track data obtained, or,
2) The track data format was
not supported, 3)
ParseDecodeData is false.
Track3Data

binary

read-only

open

Holds the track 3 data

Yes

obtained from the most

recently swept card.
Track4Data

binary

read-only

open

Holds the track 4 data (JIS-II)

No

obtained from the most

recently swept card.
Track1EncryptedData

binary

read-only

Open

Holds the encrypted track 1

data obtained from the most
recently swiped card. The
start and end sentinel values
are contained in it, and
appear only after data is
decrypted.
Encrypted data is always a
multiple of 8 bytes (when
Encryption Algorithm is
3DES) or 16 bytes (when
Encryption Algorithm is
AES) in length. And it will
be transmitted as a Hex
string. Example, 0xAB 0x00
0x09 is converted to
"AB0009".

18

Yes

SecureMag OPOS User Manual

Track1EncryptedData

int32

read-only

Open

Holds the length of the raw

Yes

track 1 data before it was

Length

encrypted.
Track2EncryptedData

binary

read-only

Open

Holds the encrypted track 2

Yes

data obtained from the most

recently swiped card. The
start and end sentinel values
are contained in it, and
appear only after data is
decrypted.
Encrypted data is always a
multiple of 8 bytes (when
Encryption Algorithm is
3DES) or 16 bytes (when
Encryption Algorithm is
AES) in length. And it will
be transmitted as a Hex
string. Example, 0xAB 0x00
0x09 is converted to
"AB0009".
Track2EncryptedData

int32

read-only

Open

Holds the length of the raw

Yes

track 2 data before it was

Length

encrypted.
Track3EncryptedData

binary

read-only

Open

Holds the encrypted track 3

Yes

data obtained from the most

recently swiped card. The
start and end sentinel values
are contained in it, and
appear only after data is
decrypted.
Encrypted data is always a
multiple of 8 bytes (when
Encryption Algorithm is
3DES) or 16 bytes (when
Encryption Algorithm is
AES) in length. And it will
be transmitted as a Hex
string. Example, 0xAB 0x00
0x09 is converted to
"AB0009".
Track3EncryptedData

int32

read-only

Open

Holds the length of the raw

track 3 data before it was

Length

encrypted.

19

Yes

SecureMag OPOS User Manual

Track4EncryptedData

binary

read-only

Open

Holds the encrypted track 4

No

data obtained from the most

recently swiped card.
Track4EncryptedData

binary

read-only

Open

Holds the length of the raw

No

track 4 data before it was

Length

encrypted.
AdditionalSecurityInf

binary

read-only

Open

Holds additional

Yes

security/encryption

ormation

information when a
DataEvent is delivered. For
example DUKPT sequence
number in it.
This data is always 10 bytes
in length. And it will be
transmitted as a Hex string.
Example, 0xAB 0x00 0x09 is
converted to "AB0009".
CardAuthenticationD

binary

read-only

Open

Holds card authentication

No

information when a

ata

DataEvent is delivered.
CardAuthenticationD

int32

read-only

Open

This property will be zero if

No

CapCardAuthentication is an

ataLength

empty string.
DeviceAuthenticated

CardType

boolean

string

read-only

read-only

Open

If the device supports

No

&

authentication the service

--Secure

Claim

must keep the value of this

Mag

&

property up to date when the

v3.24

Enabl

device is enabled.

MSR_SUE_DEVICE_AUTH

Yes

ENTICATED or

--Other

MSR_SUE_DEVICE_DEAU

Firmware

THENTICATED.

Version

Holds the card type identifier

Yes

open

for the most recently swiped

card. Value is one of them
(BANK,AAMVA and
empty).
CardTypeList

string

read-only

open

Holds a comma separated list

Yes

of string names of card types

supported by the Service.
Value is BANK and
AAMVA.
CardPropertyList

string

read-only

open

20

Holds a comma separated list

Yes

SecureMag OPOS User Manual

of the names of the properties
parsed from the most recently
swiped card.

Property Group5---ParsedData
Name

Type

Mutability

Use

Description

Support?

Holds the account number

Yes

After
AccountNumber

string

read-only

Open

obtained from the most

recently swept card.
it is initialized to NULL if:
1) The field was not included
in the track data obtained, or,
2) The track data format was
not supported, or, 3)
ParseDecodeData is false.
ExpirationData

string

read-only

Open

Holds the expiration date

Yes

obtained from the most

recently swept card.

Others

are same as AccountNumber.

FirstName

string

read-only

Open

Holds the first name obtained

Yes

from the most recently swept

card.

Others are same as

AccountNumber.
MiddleInitial

string

read-only

Open

Holds the middle initial

Yes

obtained from the most

recently swept card.

Others

are same as AccountNumber.

Surname

string

read-only

Open

Holds the surname obtained

Yes

from the most recently swept

card.

Others are same as

AccountNumber.
Title

string

read-only

Open

Holds the title obtained from

Yes

the most recently swept card..

Others are same as
AccountNumber.
Suffix

string

read-only

Open

Holds the suffix obtained from

Yes

the most recently swept card..

Others are same as
AccountNumber.
ServiceCode

string

read-only

Open

21

Holds the service code

Yes

SecureMag OPOS User Manual

obtained from the most
recently swept card.

Others

are same as AccountNumber.

Property Group6--- Statistic

Name

Type

Mutability

Use

Expected Result

After
CapStatisticsReporting

boolean

read-write

Open

Test
Result

If true ,the SO can get device

No

information to a XML statistics

CapUpdateStatistics

Bolean

read-write

Open

If true ,the SO can update the

No

XML statistics

Property Group7---Firmware
Name

Type

Mutability

Use

Expected Result

After
CapCompareFirmware

boolean

read-write

Open

Result
If true ,the SO can compare the

No

Firmware version

Version
CapUpdateFirmware

Test

boolean

read-write

Open

If true ,the SO can update the

No

firmware of the device

CapWritableTracks

Int32

Read_only

Open

This capability indicates if the

No

SecureMag device supports the

writing of track data - and
which tracks are supported.
EncodingMaxLength

Int32

Read_only

Open

The maximum length of data

No

that can be written by the

SecureMag to the track(s).
TracksToWrite

Int32

Read-Write

Open

Holds the SecureMag track(s)

No

that will be written.

CapDataEncryption

Int32

Read_only

Open

Holds a bitwise indication of

the encryption algorithms
supported by the device and
selectable via the
DataEncryptionAlgorithm

22

Yes

SecureMag OPOS User Manual

property. MSR_DE_NONE:
Data encryption is not enabled.
MSR_DE_3DEA_DUKPT:
Triple DES Derived Unique
Key Per Transaction.
MSR_DE_AES_DUKPT
(value:3): Advanced
Encryption Standard Derived
Unique Key Per Transaction.
DataEncryptionAlgorit

Int32

Read-Write

hm

Open

Holds the encryption algorithm

&

that will be used to encrypt the

Claim

track data. This property may

Yes

be set to one of the supported

encryption algorithms as
defined in the
CapDataEncryption property.
MSR_DE_NONE: Data
encryption is not enabled.
CapTrackDataMaskin

boolean

Read_only

Open

This value will be true if the

Yes

Service is capable of masking

track data.
CapCardAuthenticatio

string

Read_only

Open

Holds the type, if any, of card

No

authentication data that is

supported by the device.

CapDeviceAuthenticati

Int32

Read_only

Open

on

Holds the level of device

No

authentication supported by the

--Secure

service.

Mag

MSR_DA_NOT_SUPPORTE

v3.24

D: The service does not support

device authentication.

Yes

MSR_DA_OPTIONAL: The

--Other

service supports device

Firmware

authentication but does not

Version.

require it.
MSR_DA_REQUIRED:The
service requires device
authentication.
DeviceAuthenticationP

Int32

Read_only

Open

rotocol

Holds the device authentication

No

protocol supported by the

--Secure

device. MSR_AP_NONE:The

Mag

service does not support device

v3.24

authentication.

23

SecureMag OPOS User Manual

MSR_AP_CHALLENGERESP

Yes

ONSE:The service supports the

--Other

challenge response protocol.

Firmware
Version.

WriteCardType

string

Read-Write

Open

Holds the card type to be used

No

the next time the writeTracks

method is called.

5.3. Events of MSR

These events are fired by the Service Object when it is necessary. The following functions are, in
fact, the event-handlers that can be added into the applications. Then the applications can receive
these events and do some processing accordingly. Please refer to the UnifiedPOS Specification for
detailed information.
1) DataEvent
Syntax
void DataEvent (LONG Status);
The Status parameter contains the input status. Its value is Control-dependent,
and may describe the type or qualities of the input.
Remarks
Fired to present input data from the device to the application.
Description a DataEvent can be received when a magnetic card is swiped if the three
conditions are all met:
1) DeviceEnabled = TRUE
2) FreezeEvents = FALSE
3) DataEventEnabled = TRUE.
The track data can be obtained, and the parsed data can also be obtained if ParseDecodeData
is TRUE.
Support?
Yes
2) DirectIO Event
Syntax
void DirectIOEvent (LONG EventNumber, LONG* pData, BSTR* pString);
Parameter Description
EventNumber Event number. Specific values are assigned by the
Service Object.
pData
Pointer to additional numeric data. Specific values vary
by EventNumber and the Service Object.
pString
Pointer to additional string data. Specific values vary by
EventNumber and the Service Object.
Remarks
Fired by a Service Object to communicate directly with the application.
Support?
No
Description The event DirectIOEvent is used for some special communication between one
SO and an application. Currently, this event is not fully implemented.
3) Error Event
Syntax
void ErrorEvent (LONG ResultCode, LONG ResultCodeExtended,
24

SecureMag OPOS User Manual

LONG ErrorLocus, LONG* pErrorResponse);
Parameter Description
ResultCode
Result code causing the error event. See ResultCode
for values.
ResultCodeExtended Extended result code causing the error event. See
ResultCodeExtended for values.
ErrorLocus
Location of the error. See values below.
PErrorResponse
Pointer to the error event response. See values below.
when ErrorReportingType property is MSR_ERT_TRACK, and ErrorCode is E_EXTENDED,
then ErrorCodeExtended contains Track-level status, broken
down as follows:
Byte3

Byte2

Byte1

Byte0

Track 4

Track 3

Track 2

Track 1

Remarks Fired when an error is detected and the Controls State transitions into the error state.
NOTICE: The error type is only one E_FAILURE (Other or general error) while any error is

raised from reading card of SecureMag device. Because the SecureMag hardware cannot support
discerning wrong type.
Support?
Yes
4) StatusUpdate Event
Syntax
void StatusUpdateEvent (LONG Status);
The Status parameter is for device class-specific data, describing the type of status change.
Remarks
Fired when a Control needs to alert the application of a device status change.
Note
The SecureMag hardware cannot support the notification of power status change.
Support?
Yes
Description
SecureMag.

It is not implemented by the SO for the power status cannot be inquired from the

25

SecureMag OPOS User Manual

6. Programming Examples
There are three simple programming simple examples provided in this section
including VC++6.0, VB6.0, and VS2005/2008 C#. The examples include basic
operations and event handling.
In general, there are two steps to work with the OPOS control object:
1. Insert the OPOS Control Object (CO) into the project
2. Add an event handle
6.1. Visual C++ 6.0 Programming Example
Programming Environment:
Windows XP Pro, Visual C++ 6.0, OPOS CO 1.13. ID TECH SO 1.13.307
1. Download the OPOS driver and demo from the IDTECH website
www.idtechproducts.com. Install the driver and make sure the OPOS demo is
functioning.
2. In Visual C++ 6.0, create a Dialog Based MFC application using MFC
Application Wizard with ActiveX supports.
3. Go to Project Add to Project Components and Controls. From the
Registered ActiveX Controls folder, select OPOS MSR Control 1.13.001, and
insert this ActiveX control into the project. An icon for OPOS MSR will be added
to the Controls toolbar.

4. Add the OPOS MSR CO to the project dialog.

26

SecureMag OPOS User Manual

5. Add DataEvent and ErrorEvent handle

void CMfc_diagDlg::OnDataEventMsr1(long Status)

6. Go the View->ClassWizard and select the Member Variables tab. Select

IDC_MSR and add a member variable of type COPOSMSR, name it m_msr.

7. Create a button on the form and add the following initialization code:
void CMfc_diagDlg::OnButton1()
{
if (m_msr.Open("IDTECH_SECUREMAG_USBKB") == 0)
//0 is OPOS_SUCCESS
//" IDTECH_SECUREMAG_PS/2KB" for ps2 interface SecureMag device.
//" IDTECH_MMII_USBKB" for USBKB interface MiniMag2 device.
//" IDTECH_MMII_PS/2KB" for ps2 interface MiniMag2 device.

27

SecureMag OPOS User Manual

{
m_msr.ClaimDevice(100);
m_msr.SetDeviceEnabled(TRUE);
m_msr.SetDataEventEnabled(TRUE);
}
else {
// something wrong ...
}
}

8. Add code for DataEvent handle

void CMfc_diagDlg::OnDataEventMsr1(long Status)
{
MessageBox(m_msr.GetTrack1Data(), "Track 1 data");
m_msr.SetDataEventEnabled(TRUE); // prepare the next event.
}

9. Compile and run the program. Compile and run the program. Click on Button1
to initialize the reader and swipe a card. Track 1 data will show up in a message
box.

6.2. Visual Basic 6.0 Programming Example

Programming Environment:
Windows XP Professional, Visual Basic 6.0, OPOS CO 1.13. ID TECH SO 1.13.307
1. Create a new project of type Standard EXE.
2. From Project->Components, select OPOS MSR Control 1.13.001 and click
apply. The OPOS MSR icon will be added to the control toolbar.

28

SecureMag OPOS User Manual

3. Add an OPOS MSR control to the form. Double click on the control to add
DataEvent handle.

4. Add the initialization code:

Private Sub Form_Load()
OPOSMSR1.Open ("IDTECH_SECUREMAG_USBKB ")
//" IDTECH_SECUREMAG_PS/2KB" for ps2 interface SecureMag device.
//" IDTECH_MMII_USBKB" for USBKB interface MiniMag2 device.
//" IDTECH_MMII_PS/2KB" for ps2 interface MiniMag2 device.
OPOSMSR1.ClaimDevice (100)
OPOSMSR1.DeviceEnabled = True
OPOSMSR1.DataEventEnabled = True

29

SecureMag OPOS User Manual

End Sub

5. Add the code for Event Handle

Private Sub OPOSMSR1_DataEvent(ByVal Status As Long)
MsgBox OPOSMSR1.Track1Data
OPOSMSR1.DataEventEnabled = True
End Sub

6. Run program and swipe a card. The track 1 data will show up in a message box.

30

SecureMag OPOS User Manual

6.3. Visual Studio 2005/2008 C# Programming Example

Programming Environment:
Windows XP Professional, Visual Studio 2005/2008 C#, OPOS CO 1.13.001 ID
TECH SO 1.13.307
1. Create a Windows Application Project.
2. Right click on the Toolbox tool bar, select Choose item . Under COM
Components tab, select OPOS MSR Control 1.13.001 and click okay.

3. Add OPOS MSR Control to Form1. Double click on the OPOS MSR Control
to add DataEvent handler code. Notice that the device name might need to be changed
for different interface.

31

SecureMag OPOS User Manual

private void Form1_Load(object sender, EventArgs e)

{
if (axOPOSMSR1.Open("IDTECH_SECUREMAG_USBKB") == 0)
//0 is OPOS_SUCCESS
//" IDTECH_SECUREMAG_PS/2KB" for ps2 interface SecureMag device.
//" IDTECH_MMII_USBKB" for USBKB interface MiniMag2 device.
//" IDTECH_MMII_PS/2KB" for ps2 interface MiniMag2 device.
{
axOPOSMSR1.ClaimDevice(100);
axOPOSMSR1.DeviceEnabled = true;
axOPOSMSR1.DataEventEnabled = true;
}
}
private void axOPOSMSR1_DataEvent(object sender,
AxOposMSR_1_13_Lib._IOPOSMSREvents_DataEventEvent e)
{
MessageBox.Show(axOPOSMSR1.Track1Data, "Track 1 data");
axOPOSMSR1.DataEventEnabled = true;
}

32

SecureMag OPOS User Manual

4. Run the program and swipe a card. Track 1 data will be displayed in a window.

33

SecureMag OPOS User Manual

7. Result Code/Error Code List

const
const
const
const
const
const
const
const
const
const
const
const
const
const
const

LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG
LONG

OPOS_SUCCESS
OPOS_E_CLOSED
OPOS_E_CLAIMED
OPOS_E_NOTCLAIMED
OPOS_E_NOSERVICE
OPOS_E_DISABLED
OPOS_E_ILLEGAL
OPOS_E_NOHARDWARE
OPOS_E_OFFLINE
OPOS_E_NOEXIST
OPOS_E_EXISTS
OPOS_E_FAILURE
OPOS_E_TIMEOUT
OPOS_E_BUSY
OPOS_E_EXTENDED

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

34

0;
101;
102;
103;
104;
105;
106;
107;
108;
109;
110;
111;
112;
113;
114;