MagTek STX99875340 User Manual
EXCELLA
&
EXCELLA STX
WINDOWS API SPECIFICATIONS
PROGRAMMING REFERENCE MANUAL
MANUAL PART NUMBER 99875340-10
MAY 2014
REGISTERED TO ISO 9001:2008
1710 Apollo Court
Seal Beach, CA 90740
Phone: (562) 546-6400
FAX: (562) 546-6301
Technical Support: (651) 415-6800
www.magtek.com
ii
Copyright© 2004 – 2014
Rev Number
Date
Notes
1
30 Mar 06
Initial Release
2
15 Feb 07
Added new Sections 4, 5, 6, and 7. Move old Section 4
to new Section 8. Miscellaneous editorial changes.
3
13 Jun 07
Added new Appendix C for Mitek ImageScore.
4
16 Nov 09
Added JPEGQG and JPEGQC
5
22 Dec 09
Added StartTimeout, ExpressCapable, ExpressEnabled,
USBSpeed
6
7 Jun 2010
Added MICROptions section
7
5 Apr 2011
Added MTMICRSetConfigFile function and error codes
67, 68, 69, and 70.
8
23 Oct 2011
Added new option for <ProcessOptions><DocFeed>
9
1 Mar 2012
Updated MagneSafe MSR info for clarification
10
6 May 2014
Updated requirements for Virtual Endorsing; minor
formatting corrections
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.
ExcellaTM is a trademark of MagTek, Inc.
Microsoft® is a trademark of Microsoft Corporation.
REVISIONS
iii
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
THE 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 the prior written
authorization of the Licensor. If Licensee transfers the Software without authorization, all rights granted under this
Agreement are automatically terminated.
COPYRIGHT: The Software is copyrighted. Licensee may not copy the Software except for archival purposes or to load for
execution purposes. All other copies of the Software are in violation of this Agreement.
TERM: This Agreement is in effect as long as Licensee continues the use of the Software. The Licensor also reserves the
right to terminate 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.
LIMITED WARRANTY: Licensor warrants to the Licensee that the disk(s) or other media on which the Software is
recorded are free from defects in material or workmanship under normal use.
THE SOFTWARE IS PROVIDED AS IS. LICENSOR MAKES NO OTHER 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 inure to the benefit of MagTek,
Incorporated, its successors or assigns.
ACKNOWLEDGMENT: LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT,
UNDERSTANDS ALL OF 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.
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.
iv
TABLE OF CONTENTS
SECTION 1. OVERVIEW ............................................................................................................................. 1
REQUIREMENTS .................................................................................................................................... 1
SECTION 2. EXCELLA SOFTWARE ARCHITECTURE ............................................................................. 3
TERM DESCRIPTION ............................................................................................................................. 4
DEVICES ATTACH THROUGH USB NETWORK CARD........................................................................ 4
RNDIS SUPPORT FOR A USB NETWORK DEVICE ............................................................................. 5
SUPPORT FOR EXCELLA DEVICE ON PC SIDE: ................................................................................. 6
HOW TO COMMUNICATE WITH EXCELLA USING WEB BROWSER ................................................. 6
Get Device Status ................................................................................................................................... 8
Get Device Usage ................................................................................................................................... 9
HOW TO COMMUNICATE WITH EXCELLA USING THE EXCELLA API ............................................ 10
API FUNCTIONS.................................................................................................................................... 11
SOFTWARE FLOW FOR CHECK PROCESSING ................................................................................ 12
HOW TO PROCESS DOCUMENT USING EXCELLA API ................................................................... 13
HOW TO GET CHECK IMAGES ........................................................................................................... 14
PROCESS OPTIONS ............................................................................................................................ 14
ERROR REPORTING ............................................................................................................................ 14
DEBUGGING API................................................................................................................................... 14
SECTION 3. EXCELLA API ....................................................................................................................... 15
MTMICRGetDevice ................................................................................................................................ 15
Parameters .......................................................................................................................................... 15
Return Values ....................................................................................................................................... 15
Remarks .............................................................................................................................................. 15
Example ............................................................................................................................................... 15
MTMICROpenDevice ............................................................................................................................. 16
Parameters .......................................................................................................................................... 16
Return Values ....................................................................................................................................... 16
Remarks .............................................................................................................................................. 16
Example ............................................................................................................................................... 16
MTMICRCloseDevice ............................................................................................................................. 17
Parameters .......................................................................................................................................... 17
Return Values ....................................................................................................................................... 17
Remarks .............................................................................................................................................. 17
Example ............................................................................................................................................... 17
MTMICRDeviceConnect ........................................................................................................................ 18
Parameters .......................................................................................................................................... 18
Return Values ....................................................................................................................................... 18
Remarks .............................................................................................................................................. 18
Example ............................................................................................................................................... 19
MTMICRDeviceDisconnect .................................................................................................................... 19
Parameters .......................................................................................................................................... 19
Return Values ....................................................................................................................................... 19
Remarks .............................................................................................................................................. 19
Example ............................................................................................................................................... 19
MTMICRSetValue .................................................................................................................................. 20
Parameters .......................................................................................................................................... 20
Return Values ....................................................................................................................................... 20
Remarks .............................................................................................................................................. 20
Example ............................................................................................................................................... 21
MTMICRSetIndexValue ......................................................................................................................... 21
Parameters .......................................................................................................................................... 21
Return Values ....................................................................................................................................... 21
Remarks .............................................................................................................................................. 22
Example ............................................................................................................................................... 22
MTMICRGetValue .................................................................................................................................. 22
Parameters .......................................................................................................................................... 22
v
Return Values ....................................................................................................................................... 23
Remarks .............................................................................................................................................. 23
Example ............................................................................................................................................... 23
MTMICRGetIndexValue ......................................................................................................................... 24
Parameters .......................................................................................................................................... 24
Return Values ....................................................................................................................................... 24
Example ............................................................................................................................................... 25
MTMICRQueryInfo ................................................................................................................................. 25
Parameters .......................................................................................................................................... 26
Return Values ....................................................................................................................................... 26
Remarks .............................................................................................................................................. 26
Example ............................................................................................................................................... 26
MTMICRSendCommand ........................................................................................................................ 27
Parameters .......................................................................................................................................... 27
Return Values ....................................................................................................................................... 27
Remarks .............................................................................................................................................. 27
Example ............................................................................................................................................... 28
MTMICRProcessCheck .......................................................................................................................... 28
Parameters .......................................................................................................................................... 28
Return Values ....................................................................................................................................... 29
Remarks .............................................................................................................................................. 29
Example ............................................................................................................................................... 29
MTMICRGetImage ................................................................................................................................. 30
Parameters .......................................................................................................................................... 30
Return Values ....................................................................................................................................... 30
Remarks .............................................................................................................................................. 31
Example ............................................................................................................................................... 31
MTMICRGetImages ............................................................................................................................... 32
Parameters .......................................................................................................................................... 32
Return Values ....................................................................................................................................... 33
Remarks .............................................................................................................................................. 33
Example ............................................................................................................................................... 34
MTMICRGETSECTIONCOUNT ............................................................................................................. 34
Parameters .......................................................................................................................................... 35
Return Values ....................................................................................................................................... 35
Remarks .............................................................................................................................................. 35
Example ............................................................................................................................................... 35
MTMICRGetSectionName ..................................................................................................................... 36
Parameters .......................................................................................................................................... 36
Return Values ....................................................................................................................................... 36
Remarks .............................................................................................................................................. 36
Example ............................................................................................................................................... 37
MTMICRGetKeyCount ........................................................................................................................... 37
Parameters .......................................................................................................................................... 38
Return Values ....................................................................................................................................... 38
Remarks .............................................................................................................................................. 38
Example ............................................................................................................................................... 39
MTMICRGetKeyName ........................................................................................................................... 40
Parameters .......................................................................................................................................... 40
Return Values ....................................................................................................................................... 40
Remarks .............................................................................................................................................. 41
Example ............................................................................................................................................... 41
MTMICRSetTimeout............................................................................................................................... 42
Parameters .......................................................................................................................................... 42
Return Values ....................................................................................................................................... 42
Example ............................................................................................................................................... 42
MTMICRGetTimeout .............................................................................................................................. 43
Parameters .......................................................................................................................................... 43
vi
Return Values ....................................................................................................................................... 43
Example ............................................................................................................................................... 43
MTMICRLogEnable ................................................................................................................................ 44
Parameters .......................................................................................................................................... 44
Return Values ....................................................................................................................................... 44
Example ............................................................................................................................................... 44
MTMICRSetLogFileHandle .................................................................................................................... 44
Parameters .......................................................................................................................................... 44
Return Values ....................................................................................................................................... 44
Example ............................................................................................................................................... 45
MTMICRSETLOGLEVEL ....................................................................................................................... 45
Parameters .......................................................................................................................................... 45
Return Values ....................................................................................................................................... 46
Example ............................................................................................................................................... 46
Remarks .............................................................................................................................................. 46
MTMICRCOMInitialize ........................................................................................................................... 46
Parameters .......................................................................................................................................... 46
Return Values ....................................................................................................................................... 46
Example ............................................................................................................................................... 46
MTMICRCOMUnInitialize ....................................................................................................................... 47
Parameters .......................................................................................................................................... 47
Return Values ....................................................................................................................................... 47
Example ............................................................................................................................................... 47
Remark ................................................................................................................................................ 47
MTMICRSetConfigFile ........................................................................................................................... 48
Parameters .......................................................................................................................................... 48
Return Values ....................................................................................................................................... 48
Example ............................................................................................................................................... 48
Remark ................................................................................................................................................ 48
SECTION 4. COMMANDS SENT TO DEVICE .......................................................................................... 49
MSR COMMAND ................................................................................................................................... 49
SETLED Command ................................................................................................................................ 49
LEDn Parameter ................................................................................................................................... 49
LDURn Parameter ................................................................................................................................ 50
Example ............................................................................................................................................... 50
SECTION 5. KEYS SENT TO DEVICE ...................................................................................................... 51
SECTION = Application .......................................................................................................................... 53
Transfer ................................................................................................................................................ 53
DocUnits ............................................................................................................................................... 53
SECTION = ProcessOptions .................................................................................................................. 53
ReadMICR ............................................................................................................................................ 53
Endorse ................................................................................................................................................ 53
RespondEarly ....................................................................................................................................... 54
DblPickDet ........................................................................................................................................... 54
DocFeed ............................................................................................................................................... 54
DocFeedTimeout .................................................................................................................................. 54
KVErrStop ............................................................................................................................................. 54
MICRFmtCode ...................................................................................................................................... 55
Sequence ............................................................................................................................................. 55
ScanOnce ............................................................................................................................................. 58
SECTION = Endorser ............................................................................................................................. 58
PrintData.............................................................................................................................................. 58
PrintFrontData ..................................................................................................................................... 58
PrintFont .............................................................................................................................................. 59
PrintFrontFont ...................................................................................................................................... 59
PrintStyle ............................................................................................................................................. 59
PrintFrontStyle ..................................................................................................................................... 59
vii
PrintRate .............................................................................................................................................. 59
Virtual .................................................................................................................................................. 60
PrintFontSize ........................................................................................................................................ 60
PrintFrontFontSize ................................................................................................................................ 60
BackXPosition ...................................................................................................................................... 60
FrontXPostion....................................................................................................................................... 62
BackYPosition ...................................................................................................................................... 62
FrontYPosition ...................................................................................................................................... 62
YPositionOffset .................................................................................................................................... 62
SECTION = ImageOptions ..................................................................................................................... 63
Number ................................................................................................................................................ 63
ImageColor# ........................................................................................................................................ 63
Resolution# .......................................................................................................................................... 63
Compression# ...................................................................................................................................... 63
FileType#.............................................................................................................................................. 64
ImageSide# .......................................................................................................................................... 64
FilterB .................................................................................................................................................. 64
FilterG .................................................................................................................................................. 64
JPEGQC ................................................................................................................................................ 65
JPEGQG ................................................................................................................................................ 65
CalculateSHA1 ..................................................................................................................................... 65
ScanLED1, ScanLED2 ........................................................................................................................... 65
Example for setting up ImageOptions key-value pairs to obtain 4 Images ............................................. 66
SECTION = MICROptions...................................................................................................................... 67
Threshold ............................................................................................................................................. 67
Quality .................................................................................................................................................. 67
SECTION 6. KEYS RECEIVED FROM DEVICE ....................................................................................... 69
SECTION = CommandStatus ................................................................................................................ 71
CheckDS .............................................................................................................................................. 71
ReturnCode .......................................................................................................................................... 71
ReturnMsg ........................................................................................................................................... 71
KVErrCnt ............................................................................................................................................... 71
KVErrCode# .......................................................................................................................................... 71
KVErrVal# ............................................................................................................................................. 72
RETURN CODES AND MESSAGES FROM EXCELLA AND EXCELLA STX ................................................... 72
SECTION = DocInfo ............................................................................................................................... 75
DocUnits ............................................................................................................................................... 75
DocWidth ............................................................................................................................................. 75
DocHeight ............................................................................................................................................ 75
MICRFont ............................................................................................................................................. 75
MICRRaw ............................................................................................................................................. 76
MICRAcct ............................................................................................................................................. 76
MICRAmt .............................................................................................................................................. 76
MICRAux .............................................................................................................................................. 76
MICRBankNum..................................................................................................................................... 76
MICRChkType ....................................................................................................................................... 77
MICRCountry ........................................................................................................................................ 77
MICRDecode ........................................................................................................................................ 77
MICREPC .............................................................................................................................................. 77
MICROnUs ............................................................................................................................................ 77
MICROut ............................................................................................................................................... 78
MICRSerNum ....................................................................................................................................... 78
MICRTPC .............................................................................................................................................. 78
MICRTransit ......................................................................................................................................... 78
MICRParseSts0 .................................................................................................................................... 79
MICRParseSts1 .................................................................................................................................... 80
SECTION = ImageInfo ........................................................................................................................... 81
viii
ImageSize# .......................................................................................................................................... 81
ImageURL# .......................................................................................................................................... 81
ImageSHA1Key# .................................................................................................................................. 81
Number ................................................................................................................................................ 82
SECTION = MSRInfo ............................................................................................................................. 82
CardType .............................................................................................................................................. 82
MPData ................................................................................................................................................ 82
MPStatus ............................................................................................................................................. 82
TrackData1 .......................................................................................................................................... 82
TrackData2 .......................................................................................................................................... 83
TrackData3 .......................................................................................................................................... 83
TrackStatus1 ........................................................................................................................................ 83
TrackStatus2 ........................................................................................................................................ 83
TrackStatus3 ........................................................................................................................................ 83
EncryptedTrackData1 ........................................................................................................................... 84
EncryptedTrackData2 ........................................................................................................................... 84
EncryptedTrackData3 ........................................................................................................................... 84
DeviceSerialNumber ............................................................................................................................. 84
EncryptedSessionID .............................................................................................................................. 84
DUKPTserialnumber ............................................................................................................................. 84
SECTION 7. OTHER KEYS AVAILABLE FROM DEVICE ....................................................................... 85
SECTION = DeviceUsage ...................................................................................................................... 87
ChecksRead ......................................................................................................................................... 87
DocsRead ............................................................................................................................................. 87
CardsRead ........................................................................................................................................... 87
CardsScanned ...................................................................................................................................... 87
HoursOp ............................................................................................................................................... 87
HoursOn ............................................................................................................................................... 88
InkUsed ................................................................................................................................................ 88
FrontInkUsed ........................................................................................................................................ 88
SECTION = DeviceCapabilities ............................................................................................................. 89
AutoFeed.............................................................................................................................................. 89
IDScan ................................................................................................................................................. 89
MagStripe ............................................................................................................................................ 89
MagnePrint .......................................................................................................................................... 89
Endorse ................................................................................................................................................ 90
Firmware .............................................................................................................................................. 90
Image .................................................................................................................................................. 90
MICR .................................................................................................................................................... 90
UnitSerialNumber ................................................................................................................................. 90
Stamp .................................................................................................................................................. 91
Color .................................................................................................................................................... 91
MachineType ........................................................................................................................................ 91
USBDriver ............................................................................................................................................. 91
ExpressCapable .................................................................................................................................... 91
SECTION = DeviceStatus ...................................................................................................................... 92
State .................................................................................................................................................... 92
ManualFeeder ...................................................................................................................................... 92
AutoFeeder .......................................................................................................................................... 92
IDFeeder .............................................................................................................................................. 92
Lamp1 ................................................................................................................................................. 93
Lamp2 ................................................................................................................................................. 93
Ink ....................................................................................................................................................... 93
FrontInk ............................................................................................................................................... 93
Path ..................................................................................................................................................... 93
Printer .................................................................................................................................................. 94
FrontPrinter .......................................................................................................................................... 94
ix
RTCBattery ........................................................................................................................................... 94
ScanCalibStatus ................................................................................................................................... 94
SnsrCalibStatus .................................................................................................................................... 94
AccessGuide ......................................................................................................................................... 95
ExpressEnabled .................................................................................................................................... 95
USBSpeed ............................................................................................................................................ 95
StartTimeout ........................................................................................................................................ 95
RawSensors ......................................................................................................................................... 96
SECTION 8. EXAMPLES OF KEY-VALUE PAIRS ................................................................................... 97
EXAMPLE 1: REQUESTING TWO IMAGES WITH ENDORSEMENT AND FRANKING ..................... 97
Key-Value Pairs Sent by Host Application to Excella Device................................................................... 97
Key-Value Pairs Sent by STXDemo Application to Excella Device in XML Format ................................... 98
Key-Value Pairs Returning from Excella Device ..................................................................................... 98
Key-Value Pairs Returning From Excella Device In XML Format ............................................................ 99
EXAMPLE 2: DEVICE STATUS REPORTED BY EXCELLA DEVICE ............................................... 101
EXAMPLE 3: DEVICE CAPABILITIES REPORTED BY EXCELLA DEVICE ..................................... 101
EXAMPLE 4: DEVICE USAGE REPORTED BY EXCELLA DEVICE ................................................ 103
APPENDIX A. FORMAT LIST ................................................................................................................. 105
APPENDIX B. ERROR CODES AND MESSAGES ................................................................................ 123
APPENDIX C. HOW TO PROCESS CHECKS AND GET IMAGE QUALITY ASSURANCE ................. 125
TABLES AND FIGURES
FIGURE 2-1. EXCELLA SOFTWARE ARCHITECTURE .........................................................................................................3
FIGURE 2-2. DEVICES ATTACH THROUGH USB NETWORK CARD .....................................................................................4
FIGURE 2-3. RNDIS SUPPORT FOR A USB NETWORK DEVICE .......................................................................................5
TABLE 2-1. FUNCTIONS .............................................................................................................................................. 11
FIGURE 2-4. SOFTWARE FLOW FOR CHECK PROCESSING ........................................................................................... 12
TABLE 5-1. VALUES FOR SCAN BAR ILLUMINATION COLORS ......................................................................................... 65
TABLE 5-2. POSSIBLE COMBINATION VALUES FOR IMAGE OPTIONS .............................................................................. 66
TABLE 5-3. EXAMPLE FOR SECTION IMAGEOPTIONS – 1 THROUGH 4............................................................................ 66
TABLE 6-1. OPERATION COMPLETED .......................................................................................................................... 72
TABLE 6-2. OPERATION ............................................................................................................................................. 72
TABLE 6-3. DATA INPUT ............................................................................................................................................. 72
TABLE 6-4. PATH ...................................................................................................................................................... 73
TABLE 6-5. PRINTER ................................................................................................................................................. 73
TABLE 6-6. MICR ..................................................................................................................................................... 73
TABLE 6-7. SCAN/IMAGE ............................................................................................................................................ 74
TABLE 6-8. MISCELLANEOUS ..................................................................................................................................... 74
TABLE 6-9. MICRPARSESTS0 ................................................................................................................................ 79
TABLE 6-10. MICRPARSESTS1 .............................................................................................................................. 80
1
SECTION 1. OVERVIEW
The sections of this manual are as follows:
Section 1. Overview
Section 2. Excella Software Architecture – includes flow diagrams, screen captures, and
several “How To” descriptions.
Section 3. Excella API – describes Excella device API functions and return codes.
Section 4. Commands Sent To Device – describes commands sent by the application to the
Excella device.
Section 5. Keys Sent to Device – lists and explains keys sent to the Excella device by the
application.
Section 6. Keys Received From Device – lists and explains keys received from the Excella
device.
Section 7. Other Keys Available from Device – lists additional keys available from Excella
device.
Section 8. Examples of Key-Value Pairs
Appendix A. Format List – built-in list of MICR data formats from which the user may select
one to become the active Format every time a check is read.
Appendix B. Error codes and messages from Excella API MTXMLMCR.dll.
REQUIREMENTS
The following item is required for software installation:
P/N 22359069, API/Demo for Excella STX (CD)
For the USB interface, this CD installs USB Drivers, MTXMLMCR.dll and Demo program.
3
COMPUTER
EXCELLA DEVICE
CONNECTED VIA USB
Wininet.dll
‘C’ API to xfer data to a web
XML to Key/Value and vice versa
Application
Excella API
MSXML
‘C’ API
USB Protocol
USB Protocol
HTTP: XML
Microsoft Network Stack
USB Driver
Magtek RNDIS Layer
Network Layer TCP/IP
WEB Server
(HTTP and XML parser)
SECTION 2. EXCELLA SOFTWARE ARCHITECTURE
(For RNDIS USB Drivers Only)
The architecture of the system is shown in Figure 2-1. Descriptions of the terms and operations
used follow the illustration.
Figure 2-1. Excella Software Architecture
Excella Windows API Specifications
4
TERM DESCRIPTION
MTXMLMCR.dll.
Application provides API to upper level application to talk to the device. The application does
not have any knowledge of how the device is connected to the computer. Thus it does not
expose the transport protocol to the application. We are using HTTP protocol with XML to
communicate with the device. The MTXMLMCR.dll uses wininet.dll to talk to internet
protocols. The MTXMLMCR.dll. provides functions to convert the scan request into XML
format using msxml4.dll and then send it to the device using wininet.dll. It also provides
functions to convert the response from the device (XML format) to key/value pairs.
msxml4.dll : Microsoft XML Parser. MTXMLMCR.dll.
uses msxml4.dll to convert the key/value pair to XML language. MTXMLMCR.dll also uses
the msxml4.dll to convert the XML data back to key/ value pair.
wininet.dll: MFC Win32 Internet Extension. wininet.dll, provide access to common Internet
protocols, including Gopher, FTP, and HTTP. MTXMLMCR.dll uses wininet.dll to establish
an Internet connection with Excella device. It then communicates with Excella using GET and
POST requests provide by wininet.dll.
RNDIS: Microsoft Ethernet to USB driver that makes USB device look like an Ethernet device.
This driver supports Windows 98, ME, 2000 and XP.
DEVICES ATTACH THROUGH USB NETWORK CARD
Devices attach through the USB Network card are shown in Figure 2-2.*
Figure 2-2. Devices attach through USB Network Card
*
Figures 2-2 and 2-3 are produced by Microsoft.
Section 2. Excella Software Architecture
5
RNDIS SUPPORT FOR A USB NETWORK DEVICE
RNDIS Support for a USB Network device is shown in Figure 2-3.*
Figure 2-3. RNDIS Support for a USB Network Device
Excella Windows API Specifications
6
SUPPORT FOR EXCELLA DEVICE ON PC SIDE:
To support Excella device on the PC side, a template INF file provided by Microsoft was
modified to install the RNDIS drivers. There are two driver files provided by Microsoft:
rndismp.sys (export driver and is linked to usb8023.sys)
usb8023.sys (For an RNDIS USB Device)
When usb8023.sys is loaded the system automatically loads rndismp.sys.
Windows XP has built in support for RNDIS. Windows 2000 does not have RNDIS drivers.
MagTek supplies RNDIS driver for Windows 2000.
HOW TO COMMUNICATE WITH EXCELLA USING WEB BROWSER
Excella device can be accessed from an Internet Web browser using the IP address of the device.
An example in using the IP address of the Excella device to obtain device capabilities
information is followed.
Assuming the Excella device has IP address 192.168.10.100, type the following line in the
address box of the Web browser. Internet Explorer is used in this example:
192.168.10.100\Excella?DeviceInformation=DeviceCapabilities
Press the Enter key, and the Excella device responds with the results shown on the next page:
Section 2. Excella Software Architecture
7
Excella Windows API Specifications
8
Get Device Status
The following is an example in using the IP address of the Excella device to obtain device status
information. Assuming the Excella device has IP address 192.168.10.100, type the following line
in the address box of the Web browser. Internet Explorer is used in this example:
192.168.10.100\Excella?DeviceInformation= DeviceStatus
Press the Enter key, and the Excella device responds with the results shown below:
Section 2. Excella Software Architecture
9
Get Device Usage
The following is an example in using the IP address of the Excella device to obtain device usage
information. Assuming the Excella device has IP address 192.168.10.100, type the following line
in the address box of the Web browser. Internet Explorer is used in this example:
192.168.10.100\Excella?DeviceInformation= DeviceUsage
Press the Enter key, and the Excella device responds with the results shown below:
Excella Windows API Specifications
10
Files
Location
Description
micrdev.ini
Windows folder
This file contains a list of default
Excella connections and IP
addresses.
MTXMLMCR.dll
Windows System32 folder
Excella API
wininet.dll
Windows System32 folder.
Win32 API for Internet Protocols.
This file is provided by Microsoft
msxml4.dll
Windows System32 folder.
MSXML XML parser. ActiveX
Object for XML API. This file is
installed with the installation of
Excella API
HOW TO COMMUNICATE WITH EXCELLA USING THE EXCELLA API
The following table lists required files in order to use Excella API:
Section 2. Excella Software Architecture
11
NAME
DESCRIPTION
PAGE
MTMICRGetDevice
Get device name of all devices present.
15
MTMICROpenDevice
Opens device with the given name.
16
MTMICRCloseDevice
Closes device with the given name.
17
MTMICRDeviceConnect
Connects device with IP or DNS name.
18
MTMICRDeviceDisconnect
Disconnect device with the given IP or DNS name.
19
MTMICRSetValue
Adds a key/value pair to a given section.
20
MTMICRSetIndexValue
Adds a key/value pair with index to a given section.
21
MTMICRGetValue
Returns value of a key/value pair from a given section.
22
MTMICRGetIndexValue
Returns value of a key/value pair with index from a given
section.
24
MTMICRQueryInfo
Sends a request to a given device name to query for info
on a given query parameter.
25
MTMICRSendCommand
Sends a single command to a given device name.
27
MTMICRProcessCheck
Sends a scan request to a given device to scan with a
given process options.
28
MTMICRGetImage
Sends request to the given device name to get an image
of a previously scanned check.
30
MTMICRGetImages
Sends request to the given device name to get one or
more images of a previously scanned check.
32
MTMICRGetSectionCount
Returns the number of sections present in a given
document information.
34
MTMICRGetSectionName
Returns the section name of the given section number in
a given document information.
36
MTMICRGetKeyCount
Returns the number of keys present in a given section in
a given document information.
37
MTMICRGetKeyName
Returns the key name of the given key number in a given
document information.
40
MTMICRSetTimeout
Sets device communication timeout in milliseconds.
48
MTMICRGetTimeout
Gets device communication timeout in milliseconds.
49
MTMICRLogEnable
Enable the logging.
50
MTMICRSetLogFileHandle
Logs errors to the given file handle.
51
MTMICRSetLogLevel
Sets the level of details for logging
52
MTMICRCOMInitialize
Enable MSXML instantiation at DLL level
53
MTMICRCOMUnInitialize
Disable MSXML instantiation at DLL level
54
MTMICRSetConfigFile
Set the path and file name of the config file. Default is
"MICRDEV.INI"
55
API FUNCTIONS
Table 2-1 lists functions provided by MTXMLMCR.dll. Please refer to Section 3 for a complete
description of these functions.
Table 2-1. Functions
Excella Windows API Specifications
12
Excella Present
Successful Open Device
Select desired options for
check processing
Yes
Yes
Close Device
No
Want new option?
Continue?
No
Modify options
Yes
Send options to device
SOFTWARE FLOW FOR CHECK PROCESSING
Figure 2-4 illustrates the sequence of check processing.
Figure 2-4. Software Flow for Check Processing
Section 2. Excella Software Architecture
13
HOW TO PROCESS DOCUMENT USING EXCELLA API
To process document, follow these steps:
1. Find the attached Excella device by calling function MTMICRGetDevice.
2. Use function MTMICROpenDevice to open the device.
3. Excella is now ready to accept the XML options using function MTMICRProcessCheck.
For every document that is processed, a set of options must be sent to the device. These
options define how the document will be processed, i.e., image color, image type, image
resolution, print back, print front etc. The options are stored as key/value pairs in a
buffer. The memory for this buffer must be allocated big enough to store all selected
options. These options must be sent to the Excella device using function
MTMICRProcessCheck. Use function MTMICRSetValue and function
MTMICRSetIndexValue to store the key/value pairs in the option buffer. The options can
be set in the buffer only once.
4. Use function MTMICRProcessCheck to send the process options to the Excella device.
5. Excella processes the document with the given process options and returns the result of
the process operation. The result is stored in the third parameter of the function
MTMICRProcessCheck. The result contains only the information of the operation and
information of the device. It does not contain scanned data. Information such as the size
of the scanned images and the image identifier are included. The image information can
be found under ImageInfo section. Use function MTMICRGetValue and function
MTMICRGetIndexValue to retrieve key/value pair for image information. If there is no
error returned in the document information, use function MTMICRGetImage or function
MTMICRGetImages to get image data.
6. Go to step 4 to process the next check.
Excella Windows API Specifications
14
HOW TO GET CHECK IMAGES
To get a check image, follow these steps:
1. The function MTMICRProcessCheck contains information of the process operation
provided by Excella device after it completes document processing. Use this information
to find the information of the scanned images in the ImageInfo section. The ImageInfo
section contains the size of the image and the image identification for each image.
2. Use function MTMICRGetValue or function MTMICRGetIndexValue to retrieve the size
and the URL of each image. Allocate memory for each image according to its given size.
3. Use function MTMICRGetImage to get one image at a time or function
MTMICRGetImages to get all images at once. The image data is transferred to the buffer
that has memory allocated.
PROCESS OPTIONS
Process options are stored as key/value pairs in a buffer. The structure of the options follows
XML format. Use function MTMICRSetValue or function MTMICRSetIndexValue to add an
option to this structure. Options are string-based key/value pairs. Each option is stored only
once in the buffer. Function MTMICRGetValue and function MTMICRGetIndexValue can be used
to retrieve a key/value pair from this buffer.
ERROR REPORTING
When a document is processed, if there is an error in the Excella device or in the processing
operation, the error is returned in the function MTMICRProcessCheck . Use function
MTMICRGetValue or function MTMICRGetIndexValue to retrieve the error information. Table 4-
13 to table 4-20 list return codes and return messages from Excella.
If an error occurs due to the failure of API function, the error is returned as the return code of the
API provided by MTXMLMCR.dll. Appendix B contains a list of errors returning from
MTXMLMCR.dll
DEBUGGING API
On the Excella Demo GUI program, there is an option to enable the error logging function. If
this option is enabled, all errors returned from the device are logged into log file named
“STXDemo.log”. This file resides in the Excella Demo program installation directory.
15
SECTION 3. EXCELLA API
MTMICRGetDevice
MTMICRGetDevice function returns the device name of the device present in the system.
ULONG MTMICRGetDevice (
DWORD dwDeviceContext,
char *pcDevName
);
Parameters
dwDeviceContext
This is the device number of the device. This must be set to 1 to get the first device in the system. Increment it by 1 to get
the next device name.
pcDevName
Pointer to the buffer where the device name will be stored.
Return Values
MICR_ST_OK
MICR_ST_DEVICE_NOT_FOUND
MICR_ST_BAD_PARAMETER
Remarks
If the function succeeds, the return value is MICR_ST_OK. The device name of the device is filled in the buffer pointed by the
parameter pcDevName.
If there is no device present or there is no device that is associated with the given dwDeviceContext, then the function fails and
MICR_ST_DEVICE_NOT_FOUND is returned.
If there is no memory allocated for the pcDevName parameter, then MICR_ST_BAD_PARAMETER is returned.
Example
#define DEVICE_NAME_LEN 128
int i=1;
DWORD dwResult;
char pcDevName[DEVICE_NAME_LEN]="";
while ((dwResult = MTMICRGetDevice(i,(char*) pcDevName)) != MICR_ST_DEVICE_NOT_FOUND)
{
// Device found, increment the device number
i++;
}
Excella Windows API Specifications
16
MTMICROpenDevice
MTMICROpenDevice function opens the device with the given device name.
ULONG MTMICROpenDevice (
char *pcDevName
);
Parameters
pcDevName
Pointer to null terminated string that specifies the name of the device to open. Use function MTMICRGetDevice to
obtain the device name.
Return Values
If the function succeeds, the return value is MICR_ST_OK.
MICR_ST_OK
MICR_ST_BAD_DEVICE_NAME
MICR_ST_DEVICE_NOT_FOUND
MICR_ST_DEVICE_NOT_RESPONDING
MICR_ST_MSXML_NOT_FOUND
MICR_ST_MSXML_FAILED
Remarks
If the pcDevName is NULL, the return value is MICR_ST_BAD_DEVICE_NAME.
If no device is found, the return value is MICR_ST_DEVICE_NOT_FOUND.
If MSXML is not installed, return value is MICR_ST_MSXML_NOT_FOUND
If MSXML cannot be instantiated, return value is MICR_ST_MSXML_FAILED
If device is found but cannot connect, return value is MICR_ST_DEVICE_NOT_RESPONDING
Example
#define DEVICE_NAME_LEN 128
int i=1;
DWORD dwResult;
char pcDevName[DEVICE_NAME_LEN]="";
while ((dwResult = MTMICRGetDevice(i,(char*) pcDevName)) != MICR_ST_DEVICE_NOT_FOUND)
{
if (MTMICROpenDevice (pcDevName) == MICR_ST_OK)
{
///close the device
MTMICRCloseDevice (pcDevName);
}
i++;
}
Section 3. Excella API
17
MTMICRCloseDevice
MTMICRCloseDevice function closes the device with the given device name.
ULONG MTMICRCloseDevice (
char *pcDevName
);
Parameters
pcDevName
Pointer to null terminated string containing the name of the device to close. This is the device that is previously opened
using function MTMICROpenDevice.
Return Values
MICR_ST_OK
MICR_ST_BAD_DEVICE_NAME
MICR_ST_DEVICE_NOT_FOUND
Remarks
If the pcDevName is NULL, the return value is MICR_ST_BAD_DEVICE_NAME.
Example
#define DEVICE_NAME_LEN 128
int i=1;
DWORD dwResult;
char pcDevName[DEVICE_NAME_LEN]="";
// Get the device name at device number “i”
while ((dwResult = MTMICRGetDevice(i,(char*) pcDevName)) != MICR_ST_DEVICE_NOT_FOUND)
{
// Success in getting the device name
// Open this device
if (MTMICROpenDevice (pcDevName) == MICR_ST_OK)
{
// Now close this device
MTMICRCloseDevice (pcDevName);
}
else
{
// Error while opening this device.
}
i++;
}
Excella Windows API Specifications
18
MTMICRDeviceConnect
MTMICRDeviceConnect function connects host to a device that has the given IP address or a DNS name.
ULONG MTMICRDeviceConnect (LPSTR lpszDevice,
INTERNET_PORT nServerPort,
DWORD dwAccessType,
LPSTR lpszProxyName,
LPSTR lpszProxyBypass);
Parameters
lpszDevice: Pointer to a null terminated string that contains the IP address or DNS name of the device.
nServerPort: Unsigned integer that specifies the TCP/IP port on the server to which a connection is made.
dwAccessType: Type of Internet access. This parameter can be one of the following values:
INTERNET_OPEN_TYPE_DIRECT
INTERNET_OPEN_TYPE_PRECONFIG
INTERNET_OPEN_TYPE_PROXY
INTERNET_OPEN_TYPE_PRECONFIG_WITH_NO_AUTOPROXY
lpszProxyName: Pointer to a null-terminated string that specifies the name of the proxy server to use when proxy access
is specified by setting dwAccessType to INTERNET_OPEN_TYPE_PROXY.
lpszProxyBypass: Pointer to a null-terminated string that specifies an optional list of host names or IP
addresses, or both, that should not be routed through the proxy when dwAccessType
is set to INTERNET_OPEN_TYPE_PROXY
Return Values
If the function succeeds, the return value is MICR_ST_OK.
MICR_ST_OK
MICR_ST_BAD_DEVICE_IP_OR_DOMAIN_NAME
MICR_ST_DEVICE_NOT_RESPONDING
MICR_ST_MSXML_NOT_FOUND
MICR_ST_MSXML_FAILED
Remarks
If parameter lpszDevice is NULL, the return value is MICR_ST_BAD_DEVICE_IP_OR_DOMAIN_NAME.
If no device is found, the return value is MICR_ST_DEVICE_NOT_FOUND.
If MSXML is not installed, return value is MICR_ST_MSXML_NOT_FOUND
If MSXML cannot be instantiated, return value is MICR_ST_MSXML_FAILED
If device is found but cannot connect, return value is MICR_ST_DEVICE_NOT_RESPONDING
Section 3. Excella API
19
Example
char logString[256];
DWORD dwStatus;
dwStatus = MTMICRDeviceConnect(“192.168.10.100”,
INTERNET_DEFAULT_HTTP_PORT,
INTERNET_OPEN_TYPE_DIRECT,
“ProxyServer”,
“ProxyByPassIP”);
if(dwStatus!=MICR_ST_OK)
{
sprintf (logString, "Opening Device FAILED - ERROR %d", dwStatus);
MessageBox (logString, "Demo", MB_OK);
}
MTMICRDeviceDisconnect
MTMICRDeviceDisconnect function disconnects the device that has the given IP address or DNS name.
ULONG MTMICRDeviceDisconnect (LPSTR lpszDevice);
Parameters
lpszDevice Pointer to a null terminated string that contains the IP address or DNS name of the device. This is the device
that is previously connected using function MTMICRDeviceConnect.
Return Values
MICR_ST_OK
MICR_ST_BAD_DEVICE_IP_OR_DOMAIN_NAME
MICR_ST_DEVICE_NOT_FOUND
MICR_ST_BAD_DEVICE_IP_OR_DOMAIN_NAME
Remarks
If the parameter lpszDevice is NULL, the return value is MICR_ST_BAD_DEVICE_IP_OR_DOMAIN_NAME.
Example
char logString[256];
DWORD dwStatus;
dwStatus = MTMICRDeviceDisconnect(“192.168.10.100”);
if(dwStatus!=MICR_ST_OK)
{
sprintf( logString, "CANNOT CLOSE DEVICE - ERROR %d", dwStatus);
MessageBox (logString, "Demo", MB_OK);
}
Excella Windows API Specifications
20
MTMICRSetValue
MTMICRSetValue function adds a key/value pair to the given device settings specified in pcOptions buffer and in a given
section specified in pcSection buffer.
ULONG MTMICRSetValue (
char *pcOptions,
char *pcSection,
char *pcKey,
char *pcValue,
DWORD *pdwLength
);
Parameters
pcOptions
Pointer to null terminated string containing all key/value pairs.
pcSection
Pointer to null terminated string containing the section name.
pcKey
Pointer to null terminated string containing the key name.
pcValue
Pointer to null terminated string containing the key value. If this is NULL, then the key pcKey is deleted from the section
pcSection.
pdwLength:
Pointer to a double word that contains the size of the pcOptions buffer.
Return Values
MICR_ST_OK
MICR_ST_NOT_ENOUGH_MEMORY
MICR_ST_BAD_DATA
MICR_ST_BAD_SECTION_NAME
MICR_ST_BAD_BUFFER_LENGTH
Remarks
The functions return MICR_ST_NOT_ENOUGH_MEMORY, if the pcOptions buffer is not enough to add the new key/value
pair. The required size of the buffer is returned in pdwLength.
The minimum size of the buffer should be equal to MTMICR_OPTIONS_BUFFER_SIZE.
The MTMICRSetValue function saves the new key/value pair in the pcOptions buffer only. This function does not send this
key/value pair to the device. Use function MTMICRProcessCheck to send this key/value pair to the device.
If pcKey is NULL, the whole section pcSection will be removed from pcOptions string.
If pcValue is NULL and a key is specified, the specified key will be removed from the specified section
If pdwLength is less than the size of the results pcOptions after new key/value pair is added then
MICR_ST_NOT_ENOUGH_MEMORY is returned
Loading...