MagTek OMTD 99875144 User Manual
OMTD
OPOS FOR MAGTEK DEVICES
PROGRAMMING REFERENCE MANUAL
Manual Part Number: 99875144 Rev 3
JUNE 2003
REGISTERED TO ISO 9001:2000
1710 Apollo Court
Seal Beach, CA 90740
Phone: (562) 546-6400
FAX: (562) 546-6301
Technical Support: (651) 415-6800
www.magtek.com
Copyright© 1999-2003
MagTek®, Inc.
Printed in the United States of America
Information in this document is subject to change without notice. No part of this document may
be reproduced or transmitted in any form or by any means, electronic or mechanical, for any
purpose, without the express written permission of MagTek, Inc.
MagTek is a registered trademark of MagTek, Inc.
REVISIONS
Rev Number Date Notes
1 5 Oct 99 Initial Release
2 17 Feb 00 Section 2: Added "Registering an OLE
Programmatic ID Alias for OPOS Control Object."
Added Figure 2-1; Section 3: Added "Registering
an OLE Programmatic ID Alias for OPOS Control
Object."
3 13 Jun 03 Engineering Update for MTD Software Release
1.12. Front Matter: Added ISO line to logo,
changed Tech Support phone number, and
replaced Limited Warranty with generic software
license
ii
REGISTERED TO ISO 9001:2000
1710 Apollo Court, Seal Beach, CA 90740 MagTek Part Number 99875144-2
Voice: 562-546-6400 Fax: 562-546-6301 13 June 2003
SOFTWARE LICENSE AGREEMENT
IMPORTANT: YOU SHOULD CAREFULLY READ ALL THE TERMS, CONDITIONS AND RESTRICTIONS OF THIS LICENSE
AGREEMENT BEFORE INSTALLING THE SOFTWARE PACKAGE. YOUR INSTALLATION OF THE SOFTWARE PACKAGE
PRESUMES YOUR ACCEPTANCE OF THE TERMS, CONDITIONS, AND RESTRICTIONS CONTAINED IN THIS AGREEMENT. IF
YOU DO NOT AGREE WITH THESE TERMS, CONDITIONS, AND RESTRICTIONS, PROMPTLY RETURN THE SOFTWARE
PACKAGE AND ASSOCIATED DOCUMENTATION TO ABOVE ADDRESS ATTENTION: CUSTOMER SUPPORT.
TERMS, CONDITIONS AND RESTRICTIONS
MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to
as the "Software".
LICENSE: Licensor grants you (the "Licensee") the right to use the Software in conjunction with MagTek products.
LICENSEE MAY NOT COPY, MODIFY OR TRANSFER THE SOFTWARE IN WHOLE OR IN PART EXCEPT AS EXPRESSLY
PROVIDED IN THIS AGREEMENT. Licensee may not decompile, disassemble or in any other manner attempt to reverse engineer the
Software. Licensee shall not tamper with, bypass or alter any security features of the software or attempt to do so.
TRANSFER: Licensee may not transfer the Software or license to the Software to another party without prior written authorization of the
Licensor. If Licensee transfers the Software without authorization, all rights granted under this Agreement are automatically terminated.
COPYRIGHT:
purposes. All other copies of the Software are in violation of this Agreement.
TERM:
this Agreement if Licensee fails to comply with any of the terms, conditions or restrictions contained herein. Should Licensor terminate this
Agreement due to Licensee's failure to comply, Licensee agrees to return the Software to Licensor. Receipt of returned Software by the
Licensor shall mark the termination.
This Agreement is in effect as long as Licensee continues the use of the Software. The Licensor also reserves the right to terminate
LIMITED WARRANTY:
from defects in material or workmanship under normal use. THE SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Because of the diversity of conditions and PC hardware under
which the Software may be used, Licensor does not warrant that the Software will meet Licensee specifications or that the operation of the
Software will be uninterrupted or free of errors.
IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR
OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE.
Licensee's sole remedy in the event of a defect in material or workmanship is expressly limited to replacement of the Software disk(s) if
applicable.
GOVERNING LAW: If any provision of this Agreement is found to be unlawful, void or unenforceable, that provision shall be removed
from consideration under this Agreement and will not affect the enforceability of any of the remaining provisions. This Agreement shall be
governed by the laws of the State of California and shall insure to the benefit of MagTek, Incorporated, its successors or assigns.
The Software is copyrighted. Licensee may not copy the Software except for archival purposes or to load for execution
Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded to be free
ACKNOWLEDGMENT:
ITS TERMS, CONDITIONS AND RESTRICTIONS AND AGREES TO BE BOUND BY THEM. LICENSEE ALSO AGREES THAT
THIS AGREEMENT SUPERSEDES ANY AND ALL, VERBAL AND WRITTEN, COMMUNICATIONS BETWEEN LICENSOR AND
LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.
LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT, UNDERSTANDS ALL OF
QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED,
ATTENTION: CUSTOMER SUPPORT, AT THE ABOVE ADDRESS OR E-MAILED TO support@magtek.com.
iii
TABLE OF CONTENTS
SECTION 1. FEATURES AND REQUIREMENTS...................................................................................... 1
FEATURES...............................................................................................................................................1
REQUIREMENTS.....................................................................................................................................1
Interfacing to Applications ....................................................................................................................2
Interfacing to the Device.......................................................................................................................2
Supported Device Classes....................................................................................................... ............2
Operation..............................................................................................................................................3
COMPATIBILITY ......................................................................................................................................3
CONFIGURATION....................................................................................................................................4
REFERENCE DOCUMENTS...................................................................................................................4
SECTION 2. INSTALLATION...................................................................................................................... 5
OMTD INSTALLATION NOTES...............................................................................................................5
REGISTERING OLE PROGRAMMATIC ID ALIAS FOR OPOS CONTROL OBJECT............................6
MODIFYING AND REMOVING DEVICES...............................................................................................6
SECTION 3. IMPLEMENTATION NOTES.................................................................................................. 9
SINGLE SERVICE OBJECT .................................................................................................................... 9
POTENTIAL PROBLEMS IN WINDOWS 95/98....................................................................................... 9
MODIFYING OMTD DEVICE CONFIGURATION....................................................................................9
OPENING THE DEVICE.........................................................................................................................10
REGISTERING OLE PROGRAMMATIC ID ALIAS FOR OPOS CONTROL OBJECT..........................10
DEVICE POWER REPORTING.............................................................................................................11
SAVING DEVICE SETTINGS ACROSS CLAIM/RELEASE...................................................................11
ERROR PROCESSING..........................................................................................................................11
Reporting............................................................................................................................................11
Incompatibility Issues .........................................................................................................................12
SECTION 4. CONTROL OBJECTS.......................................................................................................... 13
COMMON INTERFACES.......................................................................................................................13
OLE Interfaces....................................................................................................................................13
Event Methods....................................................................................................................................13
Common Properties............................................................................................................................14
MAGNETIC STRIPE READER (MSR) DEVICE CLASS........................................................................17
MSR Properties..................................................................................................................................17
MSR Methods.....................................................................................................................................18
MICR Device Class ............................................................................................................................18
MICR Properties................................................................................................................................. 18
MICR Methods....................................................................................................................................19
PINPAD DEVICE CLASS.......................................................................................................................19
PINPad Properties..............................................................................................................................20
PINPad Methods ................................................................................................................................21
iv
LINE DISPLAY DEVICE CLASS............................................................................................................ 21
LDSP Properties.................................................................................................................................22
LDSP Methods ...................................................................................................................................23
USE CASES...........................................................................................................................................24
Using an OMTD Control.....................................................................................................................24
SUPPORTED DEVICE FEATURES.......................................................................................................25
Common Features..............................................................................................................................25
MSR Device Class..............................................................................................................................26
MICR Device Class ............................................................................................................................26
PINPad Device Class.........................................................................................................................27
Line Display Device Class..................................................................................................................28
APPENDIX A. GLOSSARY....................................................................................................................... 31
INDEX .........................................................................................................................................................33
FIGURE
OMTD Program Controlled Devices -----------------------------------------------------------------------------------------vi
v
OMTD
Control Objects (CO)
for
MICR, MSR, PINPad,
and Line Display
MTD
MagTek Device Drivers
Windows 95/98/NT
for
OMTD
Service Object (SO)
OMTD Program Controlled Devices
User-Supplied
Control Objects
(CO)
vi
SECTION 1. FEATURES AND REQUIREMENTS
The OMTD program is an extension of the MagTek Device Driver Program (MTD). The
OMTD Program provides an OPOS-compliant application interface to MagTek products and
works on Windows 95, 98, ME, NT, 2000, and XP. OMTD is in the form of a set of ActiveX
controls (COs) and a Service Object (SO).
OMTD is the OPOS (OLE for Retail POS) Support for MagTek Devices. It contains the Control
Objects for the MICR, MSR, PINPad, and Line Display device classes, and a Service Object.
The OMTD extensions are installed as part of the MTD installation package. When installing
the MTD drivers, you have the option to include OPOS support. Refer to the MTD
Programming Manual (99875125) for complete installation information.
Part Number Medium
30037385 MTD/OMTD Installation Package for Windows 95/98/ME/NT/2000/XP (CD)
99510030 MTD/OMTD Installation Package for Windows 95/98/ME/NT/2000/XP (WEB)
FEATURES
• OMTD is a set of COM objects that act as an extension to the MTD driver and provide an
OPOS-compliant application interface to MagTek products.
• Each control consists of a control object (CO) and a service object (SO). The CO is an
ActiveX control that exposes to applications a set of properties, methods and events defined
by OPOS for a specific device class (e.g., MICR devices, PINPads, line displays, Magnetic
Stripe Readers (MSR), etc.).
• The SO is a local in-process OLE Automation server (in a DLL) that is used by a CO to
implement the OPOS-prescribed functionality for a specific device. The SO performs this
functionality by sending one or more commands to the MTD driver using the Win32 File IO.
• In addition to the OPOS-specific functionality, each object exposes the OLE-specific
interfaces that make the control Microsoft compliant.
REQUIREMENTS
Each control provides the following functionality, to the degree supported by the particular
device class.
• Each CO and SO provides self-registration functionality.
1
OMTD OPOS for MagTek Devices
• Each CO implements the following standard OLE control interfaces thereby making the
control Microsoft OLE compliant: IDispatch, IViewObject2, IOleInPlaceObject, IOleObject,
IPersistStorage, IDataObject, and IProvideClassInfo.
• Exposes OPOS-specific device class methods and properties through the IDispatch interface.
• Each CO implements all OPOS-specific functionality for a specific device class as defined
by the OPOS Specification.
• A CO will only support MagTek SO(s).
• The SO implements the following standard OLE interfaces: IUnknown, IClassFactory, and
IDispatch.
• The SO implements a union of all supported OPOS device class interfaces.
• The SO implements the OPOS functionality by sending commands to the MTD driver using
the Win32 File IO API.
Interfacing to Applications
The OPOS Specification defines a common architecture for interfacing Windows applications
with a variety of POS devices. The CO is loaded and created by the host application or container
class whenever it needs to interact with the supported device. If an application needs to access a
combo device (one that supports multiple device classes), the application is required to create
and open several different control objects, one for each base class functionality that the device
supports.
Interfacing to the Device
The CO loads and creates a SO in response to an application requesting a device to be opened.
The CO invokes methods on the SO to request implementation of OPOS-specific functionality.
In response, the SO sends one or more commands to the MTD driver using the Win32 File IO
API to access the device functionality.
Supported Device Classes
The following OPOS device classes are supported by the SO:
• MSR (Magnetic Stripe Reader, e.g., Port Powered Swipe Reader, MiniWedge Swipe Reader)
2
Section 1. Features and Requirements
• MICR (Magnetic Ink Character Recognition Check Reader, e.g., MICR Plus, Mini MICR)
• PINPad (e.g., IntelliPIN)
• Line Display (e.g., IntelliPIN)
Operation
The requirements for operation are as follows:
• Computer system: Intel Pentium-based PC or better
• Operating system: Microsoft Windows 95/98/ME/NT/2000/XP
• Environment: Win32
• Packaging: ActiveX control (.OCX) for OMTD CO, COM in-process server (.DLL) for
OMTD SO
• Device access: OMTD accesses the device through existing MTD drivers.
COMPATIBILITY
Each of the OMTD controls is designed to be compatible with release 1.04 of the OPOS
Specification and work with any containing application or container that implements the standard
OLE mechanisms of creation and binding.
The common service object is designed to be compatible with the 1.05 version of the MTD
driver or later. The SO will function with earlier versions of MTD, but not all functionality may
be supported (e.g., data parsing).
It must be noted that the MTD driver itself does not have any knowledge about OPOS. This
gives the ability to modify the OMTD controls without having to modify the MTD drivers and
visa versa.
MTD will auto-configure OPOS parameters when it is installed and when any changes are made
to the device (e.g., add, remove, friendly name change, etc.).
3
OMTD OPOS for MagTek Devices
CONFIGURATION
The OPOS specification does not provide support for or prescribe mechanisms for configuration
of OPOS controls. To provide a service to the user, the configuration of the OMTD controls will
be integrated with the MTD class installer.
The OPOS configuration for MagTek devices is provided in a separate DLL that is invoked by
both the OMTD setup application and the MTD class installer when they want to modify the
OPOS configuration for a device.
REFERENCE DOCUMENTS
1. MagTek Device Drivers for Windows, Technical Reference Manual (P/N 99875125)
2. OLE for Retail POS, Application Programmer’s Guide, Release 1.4, September 23, 1998,
International Standard, other OLE/ActiveX compliant 32-bit operating system
3. OLE for Retail POS, Control Programmer’s Guide, Release 1.4, International Standard,
September 24, 1998, Windows 95/98, Windows NT, or other OLE/ActiveX compliant
32-bit operating system
4. Header files for VC++ and VB
5. OLE Controls Inside Out, Adam Denning, Microsoft Press, 1995
4
SECTION 2. INSTALLATION
MagTek Device Drivers (MTD) must be installed before installing the OMTD. Refer to MagTek
Device Drivers for Windows, Technical Reference Manual, P/N 99875125.
OMTD INSTALLATION NOTES
The OMTD extensions to the MTD Drivers are installed as part of the MTD installation package.
When installing the MTD drivers, check the OPOS Support option at the top of the list.
Selecting the OPOS Support option triggers the installation of all of the OMTD controls. It also
copies all CO and SO packages, and adds registry entries under the OPOS service provider key.
Additionally, all of the installed MTD devices will be configured for OPOS operation. Each
MTD driver will be mapped to the service object for all device classes supported by th e
particular device.
Note
When installing the OPOS Support on Windows 2000 and XP, you will need to
manually configure the devices by using the OMTDCFG configuration utility.
See Modifying and Removing Devices below for more information.
5
OMTD OPOS for MagTek Devices
REGISTERING OLE PROGRAMMATIC ID ALIAS FOR OPOS CONTROL OBJECT
The OPOS specification states that the OLE Programmatic IDs for OPOS control objects should
be OPOS.xxx where xxx specifies the device class of the control object (e.g., MSR, MICR,
PINPad, etc). The result of this requirement is that only one control object of a specific device
class can be registered at a single time.
By default, the OMTD installation registers aliases for the control objects’ OLE programmatic
ID, as required by the OPOS specification. The registered aliases are:
• MSR Control Object = OPOS.MSR
• MICR Control Object = OPOS.MICR
• PINPad Control Object = OPOS.PINPad
• Line Display Control Object = OPOS.LineDisplay
If it is desired to use more than one control object of a specific device class at a time, the alias
registration can be bypassed by typing a:\setup c in step #4 below.
When the alias registration is bypassed, the control objects are registered under the following
OLE programmatic IDs:
• MSR Control Object = MAGTEK.OPOS.MSR
• MICR Control Object = MAGTEK.OPOS.MICR
• PINPad Control Object = MAGTEK.OPOS.PPAD
• Line Display Control Object = MAGTEK.OPOS.LDSP
MODIFYING AND REMOVING DEVICES
After the OMTD Controls are installed, the configuration utility (OMTDCFG.EXE) can be used
to update/remove OPOS configuration for installed MagTek devices. It is copied to the
C:\ProgramFiles\MagTek\MTDInstall Folder when the OMTD controls are installed.
OMTDCFG.EXE is a Win32 console application that has the following usage:
omtdcfg [/|-][option] [class flag]
The [option] parameter can be one of the following:
• c , C = Configure OPOS support for installed MagTek devices
• d , D = Remove OPOS support for configured MagTek devices
• l , L = List currently configured MagTek devices
• ? = Display usage help
6
Loading...