MagTek EC2000 99875713 User Manual

ExpressCard 2000
Instant Issuance Card Personalization System
Programmer’s Reference (Windows SDK)
Manual Part Number:
99875713-1.01
REGISTERED TO ISO 9001:2008
MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350
www.magtek.com
0 - Table of Contents
Rev Number
Date
Notes
1.01
August 8, 2014
Initial Release from content in 99875367, 99875611 draft
Copyright © 2006 - 2014 MagTek, Inc. Printed in the United States of America
Information in this publication is subject to change without notice and may contain technical inaccuracies or graphical discrepancies. Changes or improvements made to this product will be updated in the next publication release. 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. ExpressCard 2000 is a trademark of MagTek, Inc.
Microsoft® and Windows® are registered trademarks of Microsoft Corporation.
All other system names and product names are the property of their respective owners.
Table 0-1 - Revisions
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 2 of 21
0 - Table of Contents
SAFETY
This product has been evaluated by multiple safety certification agencies, including Underwriters Laboratories (UL) and the United States Federal Communications Commission (FCC Class A and Class B), and is designed to protect both the user and the device. This document is written specifically to work in conjunction with these safety and integrity features to protect the user and the device. It is very important to follow all steps in the product documentation carefully, in the order in which they are described, and at the recommended times. Failure to do so could result in personal injury, and / or cause damage to the device, and / or void the product warranty.
SAFETY REQUIREMENTS
Caution: Never do any of the following:
DO NOT use a ground adapter plug to connect equipment to a power receptacle that lacks a ground
connection terminal.
DO NOT attempt any maintenance procedure that is not specifically described in this manual or any
other MagTek ExpressCard 2000 manual.
DO NOT remove any of the covers or guards that are fastened with screws. There are no operator-
serviceable areas within these covers.
DO NOT override or “cheat” electrical or mechanical interlock devices. DO NOT use supplies or cleaning materials for other than their intended purposes. DO NOT operate the device if you or anyone else has noticed unusual noises or odors.
Consider the following before operating the ExpressCard 2000:
Connect equipment to a properly grounded power source receptacle. If in doubt, have the receptacle
checked by a qualified electrician. Improper connection of the equipment’s grounding conductor creates a risk of electric shock.
Only place the device on a solid surface that can safely support the device’s weight. Be careful when moving or relocating the device. Use proper lifting techniques. Use materials and supplies specifically designed for MagTek equipment. Using unsuitable materials
can cause poor performance, and in some cases may be hazardous, cause damage, and / or void the device’s warranty.
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 3 of 21
1 - Table of Contents

Table of Contents

Table of Contents ............................................................................................................................... 4
1 Introduction ................................................................................................................................. 5
1.1 Product Summary ............................................................................................................... 5
1.2 About Communicating With EC2000 .............................................................................. 6
1.3 About mtecsdk.dll ............................................................................................................... 6
1.4 How to Use the ExpressCard SDK in Software Projects ................................................ 6
1.5 How to Set Up the ExpressCard SDK for Runtime ......................................................... 7
1.6 How to Debug the API ........................................................................................................ 9
1.7 How to Send a Transaction ................................................................................................ 9
2 Functions .................................................................................................................................... 10
2.1 MTECSDK_GetDevice ....................................................................................................... 10
2.2 MTECSDK_OpenDevice .................................................................................................... 11
2.3 MTECSDK_SetLogFileHandle .......................................................................................... 11
2.4 MTECSDK_LogEnable ....................................................................................................... 12
2.5 MTECSDK_SetValue .......................................................................................................... 13
2.6 MTECSDK_SetAttribute .................................................................................................... 14
2.7 MTECSDK_ProcessDoc ..................................................................................................... 15
2.8 MTECSDK_GetValue ......................................................................................................... 16
2.9 MTECSDK_GetAttribute .................................................................................................... 18
2.10 MTECSDK_QueryInfo .................................................................................................... 19
2.11 MTECSDK_SendCommand .......................................................................................... 20
2.12 MTECSDK_CloseDevice ................................................................................................ 20
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 4 of 21
1 - Introduction

1 Introduction

This manual is for programmers who wish to develop custom card personalization software that can communicate with ExpressCard 2000 (EC2000) devices. It begins with an introduction to the EC2000 device and supporting software architecture, then provides syntax for available operations.

1.1 Product Summary

ExpressCard 2000 (EC2000) is a compact instant-issuance card personalization device (CPD) that can securely, fully personalize any CR80-sized credit, debit, ATM, gift, loyalty, or membership card in as little as 90 seconds.
ExpressCard 2000 is supported by QwickCards.com and a wide range of third-party software solutions, creating a complete, secure instant issuance system for distributed locations that can be maintained and controlled centrally. With the feature-rich solution offered by EC2000, financial institutions will be able to meet current market needs and also support new card issuance trends, including smart cards, contactless cards, flat cards, and photo cards.
EC2000 uses the security of MagTek’s advanced MagneSafe™ Security Architecture, and MagnePrint®
card authentication technology for magstripe encoding. ExpressCard 2000’s physical and logical security
features exceed compliance requirements for instant issuance published by Visa® and MasterCard®.
EC2000’s MagnePrint Reference Capture Module captures and registers each card’s unique MagnePrint® signature as it is issued. This registered signature can then be used to protect legitimate cardholders by validating that the card being used at an ATM, teller window, home banking, or POS location is authentic, not a counterfeit copy.
Product features include:
Touchscreen LCD display Seven card stock hoppers (100 cards per hopper) Manual feed slot (single card processing) Magstripe encoding with MagnePrint® card authentication technology smart card encoding (contact only) Full-color image printing (two-sided) Embossing Foil tipping Rear indent printing Ethernet interface Secure enclosure with key or touchscreen unlock Physical and logical security features that exceed compliance requirements for instant issuance
published by Visa® and MasterCard®.
Card issuance supported by QwickCards.com and third-party solutions Card issuance supported from third-party software using XML key-value pairs
For detailed information about the EC2000 device from the user perspective, see the ExpressCard 2000 User Installation and Operation Manual, available from MagTek.
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 5 of 21
1 - Introduction
File
Location
Description
mtecsdk.ini
C:\Windows
This file contains a list of default ExpressCard connections and IP addresses. This file is required by mtecsdk.dll.

1.2 About Communicating With EC2000

EC2000 is a networked device which receives transactions from card personalization software in the form of HTTPS requests sent to specific URLs in its internal web server, using XML formatted according to a specification developed by MagTek. Developers of card personalization software have two options for generating these HTTPS requests in their custom software:
They can construct XML and send HTTPS requests directly. They can use the MagTek ExpressCard SDK provided in mtecsdk.dll.
Both options provide the same set of features, and from the device’s perspective both methods are practically identical, apart from possible deviations in the exact XML format and content. The advantage of using the ExpressCard SDK is that it abstracts implementation details, such as the physical connection to the device and the creation and structure of the transaction XML. This abstraction can reduce the overall maintenance cost of custom card personalization software.
This document serves primarily as a reference for the second method (constructing requests using the MagTek ExpressCard Windows SDK), which requires 33090060 ExpressCard Software Development
Kit, available from MagTek. For information about sending XML requests directly, see 99875611 ExpressCard 2000 Programmer’s Reference (XML), available from MagTek.

1.3 About mtecsdk.dll

mtecsdk.dll provides a high-level API to communicate with the device. It completely encapsulates calls to msxml4.dll to convert transactions into XML, as well as calls to wininet.dll for network communication. mtecsdk.dll also provides functions to convert the XML responses from the device into key-value pairs that can be easily retrieved without parsing the XML.

1.4 How to Use the ExpressCard SDK in Software Projects

To use the ExpressCard SDK in a custom software project, follow these steps:
1) Download 33090060 ExpressCard Software Development Kit (SDK), available from MagTek.
2) Run the setup program to install the SDK on your development workstation, noting the full
installation directory path. By default, the SDK installs to C:\Program Files (x86)\MagTek\ExpressCard (SDK) Demo, and supporting files install to various other Windows library locations.
3) Ensure the files listed in Table 1-1 have successfully been copied to the specified locations.
4) Create or open your custom software project in Visual Studio.
5) If your chosen programming language links using .h files, include mtecsdk.h located in the root
installation location of the ExpressCard SDK.
6) If your chosen programming language links using .lib files, include mtecsdk.lib located in the root
installation location of the Expresscard SDK.
7) If your chosen programming language links directly to .dll files, include mtecsdk.dll located in
C:\Windows\SysWOW64 on 64-bit workstations or C:\Windows \System32 on 32-bit workstations.
Table 1-1 - Files Required for ExpressCard SDK
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 6 of 21
1 - Introduction
File
Location
Description
mtecsdk.dll
C:\Windows\System32
ExpressCard API.
wininet.dll
C:\Windows\System32
Win32 API for Internet Protocols. This file is provided by Microsoft.
msxml4.dll
C:\Windows\System32
MSXML XML parser. ActiveX Object for XML API . This file is installed with the installation of ExpressCard 1000 API.

1.5 How to Set Up the ExpressCard SDK for Runtime

To set up the ExpressCard SDK for runtime use with the ExpressCard Demo software or any custom software, follow these steps on the host where the software is installed:
1) Install the ExpressCard SDK by following the steps in section 1.4 How to Use the ExpressCard
SDK.
2) Determine the IP address of the device you want to connect to. For details, see the Configuration
section of 99875600 ExpressCard 2000 User Installation and Operation Manual. Alternatively, if the device is registered with a DNS server, you can use the device’s registered IP name.
3) Ping the device from a command prompt to make sure there is a network route from the workstation
to the device.
4) Launch Notepad from the Windows Start menu in administrator mode by right-clicking its shortcut
and selecting Run as administrator.
5) Open C:\Windows\mtecsdk.ini in Notepad.
6) Edit the ConnectionString= line to change the IP address in the sections for both [DEVICE1] and
[DEVICE2], then save and close the file. If you can not save your changes, double-check that you have launched Notepad in administrator mode.
7) Launch Start > All Programs > MagTek> ExpressCard (SDK) Demo.
8) To connect to the device, select the Create Card tab, select the device you want to connect to in the
Device Name dropdown list, and press the Open Device button. The main text area should report Device: [Device Name] Opened Successfully (see Figure 1-1).
9) Use the various features in the Demo application to operate the device.
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 7 of 21
1 - Introduction
Figure 1-1 - ExpressCard (SDK) Demo Connected to a Device
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 8 of 21
1 - Introduction

1.6 How to Debug the API

To debug problems with sending transactions to a device, you can use the error logging function of the ExpressCard Demo GUI software. With this option enabled, all errors returned from the device are logged into log file named Demo.log in the ExpressCard Demo GUI installation folder.

1.7 How to Send a Transaction

The general sequence of function calls to create and send a transaction that produces a single card is:
1) Find the EC2000 device using MTECSDK_GetDevice.
2) Open the found device by calling using MTECSDK_OpenDevice.
3) Allocate memory to a string buffer that stores the XML to send to the device.
4) Use MTECSDK_SetValue to set each of the key-value pairs that define the card design, including
image files, text lines, magstripe data, embosser data, and so on. The key-value pairs are stored in the buffer allocated previously.
5) Send the transaction to the device using MTECSDK_ProcessDoc.
6) Examine the return value from MTECSDK_ProcessDoc to determine if an error occurred. The
return values are documented in section 2.7 MTECSDK_ProcessDoc.
7) Examine the results of the transaction returned by the device by calling MTECSDK_GetValue to
retrieve key-value pairs from the transaction information returned in the pcDocInfo buffer passed by
MTECSDK_ProcessDoc, which contains the transaction information and the device’s information.
The full list of return codes can be found in the appendices of 99875611 ExpressCard 2000 Programmer’s Reference (XML).
8) After all transactions have been sent, call MTECSDK_CloseDevice to close the connection to the
device.
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 9 of 21
2 - Functions

2 Functions

After including the ExpressCard SDK in your custom card personalization software project (see section
1.4 How to Use the ExpressCard SDK), use the functions described in the following sections to communicate with the device. For details about specific XML properties involved in transactions, see 99875611 ExpressCard 2000 Programmer’s Reference (XML).

2.1 MTECSDK_GetDevice

This function returns the name of the EC2000 device configured in mtecsdk.ini. See section 1.5 How to Set Up the ExpressCard SDK for information about that file.
ULONG MTECSDK_GetDevice ( DWORD dwDeviceContext, char *pcDevName );
Parameters: dwDeviceContext - Specifies the device number of the device. This must be set to 1 to get the first device found on the network. Increment it by 1 to get the name of the next device. pcDevName - Pointer to the buffer where the device name will be stored.
Return Values: EC_ST_OK EC_ST_DEVICE_NOT_FOUND EC_ST_BAD_PARAMETER
Remarks: If the function succeeds, the return value is EC_ST_OK, and pcDevName points to the name of the device.
If no device is present or if no device is associated with the given dwDeviceContext, the function fails and returns EC_ST_DEVICE_NOT_FOUND.
If there is no memory allocated for the pcDevName parameter, the function returns EC_ST_BAD_PARAMETER.
Example:
#define DEVICE_NAME_LEN 128 int i=1; DWORD dwResult; char pcDevName[DEVICE_NAME_LEN]="";
while ((dwResult = MTECSDK_GetDevice(i,(char*) pcDevName)) != EC_ST_DEVICE_NOT_FOUND) { // Device found, increment the device number i++; }
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 10 of 21
2 - Functions

2.2 MTECSDK_OpenDevice

This function opens a communication channel with the device specified by pcDevName.
ULONG MTECSDK_OpenDevice ( char *pcDevName );
Parameters: pcDevName - Pointer to null-terminated string that specifies the name of the device to open. Use function MTECSDK_GetDevice to obtain the device name.
Return Values: If the function succeeds, the return value is EC_ST_OK.
EC_ST_OK EC_ST_BAD_DEVICE_NAME EC_ST_DEVICE_NOT_FOUND EC_ST_DEVICE_NOT_RESPONDING EC_ST_MSXML_NOT_FOUND
Remarks: If the pcDevName is NULL, the return value is EC_ST_BAD_DEVICE_NAME. If no device is found, the return value is EC_ST_DEVICE_NOT_FOUND. If MSXML is not installed, return value is EC_ST_MSXML_NOT_FOUND If device is found but cannot connect, return value is EC_ST_DEVICE_NOT_RESPONDING
Example:
#define DEVICE_NAME_LEN 128 int i=1; DWORD dwResult; char pcDevName[DEVICE_NAME_LEN]="";
while ((dwResult = MTECSDK_GetDevice(i,(char*) pcDevName)) != EC_ST_DEVICE_NOT_FOUND) { if (MTECSDK_OpenDevice (pcDevName) == EC_ST_OK) { ///close the device MTECSDK_CloseDevice (pcDevName); } i++; }

2.3 MTECSDK_SetLogFileHandle

This function specifies a handle to a file where the SDK will log all messages and errors when logging is enabled using MTECSDK_LogEnable. By default, there is no log file.
VOID MTECSDK_SetLogFileHandle ( HANDLE hFileHandle
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 11 of 21
2 - Functions
);
Parameters: hFileHandle - File handle. All the API functions will log messages and errors to this log file.
Return Values: None.
Remarks: None.
Example:
#define DEVICE_NAME_LEN 128 int i=1; DWORD dwResult; HANDLE fileHandle; char cDeviceName[DEVICE_NAME_LEN]="";
while ((dwResult = MTECSDK_GetDevice(i,(char*) cDeviceName)) != EC_ST_DEVICE_NOT_FOUND) { if (MTECSDK_OpenDevice (cDevicesNames) == EC_ST_OK) { //Get timeout DWORD timeout; HANDLE fileHandle;
// Create log file and save the handle in fileHandle
// Pass the handle of the log file MTECSDK_SetLogFileHandle (fileHandle); ///close the device // Close the log file // Close the device } i++; }
if (MTECSDK_OpenDevice (cDevicesNames) == EC_ST_OK) { // Process documents ///close the device MTECSDK_CloseDevice (cDeviceName); }

2.4 MTECSDK_LogEnable

This function enables or disables logging. By default, logging is disabled. To enable logging, set a valid log file handle using MTECSDK_SetLogFileHandle, then call this function with bEnable = TRUE.
void MTECSDK_LogEnable ( BOOL bEnable );
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 12 of 21
2 - Functions
Parameters: bEnable - Boolean value to enable or disable logging.
Return Values: None.
Remarks: None.
Example:
if (hLogFileHandle != NULL) { MTECSDK_LogEnable(TRUE); MTECSDK_SetLogFileHandle (hLogFileHandle); }

2.5 MTECSDK_SetValue

This function adds a specified key/value pair to the device settings specified in the pcOptions buffer, in the section specified by pcSection. Each value can only be set once. After setting key/value pairs to fully define the transaction to send to the device, call MTECSDK_ProcessDoc to send the whole buffer to the device.
ULONG MTECSDK_SetValue ( char *pcOptions, char *pcSection, char *pcKey, char *pcValue, DWORD *pdwLength );
Process options are stored as key/value pairs in a buffer. The structure of the options follows XML format. Use function MTECSDK_SetValue to add an option to this structure. Options are string-based key/value pairs. Each option is stored only once in the buffer.
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. To delete the entire pcSection from the specified pcOptions buffer, set this value to NULL. pcValue - Pointer to null-terminated string containing the key to set. To delete the specified pcKey from the specified pcSection, set this value to NULL. pdwLength - Pointer to a double word that contains the size of the pcOptions buffer. The minimum size of the buffer should be equal to MTEC_OPTIONS_BUFFER_SIZE.
Return Values: EC_ST_OK EC_ST_NOT_ENOUGH_MEMORY EC_ST_BAD_DATA EC_ST_BAD_SECTION_NAME EC_ST_BAD_BUFFER_LENGTH
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 13 of 21
2 - Functions
Remarks: If the pcOptions buffer is not large enough to add the new key/value pair, the function returns EC_ST_NOT_ENOUGH_MEMORY, and the required size of the buffer is returned in pdwLength.
If pdwLength is less than the size of the results pcOptions after new key/value pair is added, the functions returns EC_ST_NOT_ENOUGH_MEMORY.
Example:
char Settings [4096]; DWORD SettingsBufferSize;
// Initialize Settings
// Initialize the Settings variable first SettingsBufferSize =4096;
// Set a value of “4” to the key “Number” in section “ImageOptions”and // store this new key/value pair in the buffer” Settings” dwStatus=MTECSDK_SetValue(Settings, "ImageOptions","Number","4", &SettingsBufferSize);

2.6 MTECSDK_SetAttribute

This function modifies the pcOptions buffer to set an attribute inside the XML tag specified by pcSection and pcKey (for example, it can add an id tag of the form <mytag id=5>.
ULONG MTECSDK_SetAttribute ( char *pcOptions, char *pcSection, char *pcKey, char *pcValue, DWORD *pdwLength );
Parameters: pcOptions - Pointer to null-terminated string buffer 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. To remove the whole pcSection from the pcOptions buffer, set pcKey to NULL. pcValue - Pointer to null-terminated string containing the attribute value to set. pdwLength - Pointer to a double word that contains the size of the pcOptions buffer. The minimum size of the buffer should be equal to MTEC_OPTIONS_BUFFER_SIZE.
Return Values: EC_ST_OK EC_ST_NOT_ENOUGH_MEMORY EC_ST_BAD_DATA EC_ST_BAD_SECTION_NAME EC_ST_BAD_BUFFER_LENGTH
Remarks:
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 14 of 21
2 - Functions
If the pcOptions buffer is not large enough to add the new attribute, the function returns EC_ST_NOT_ENOUGH_MEMORY, and returns the required size of the buffer in pdwLength.
If pdwLength is less than the size of pcOptions after the new attribute is added, the function returns EC_ST_NOT_ENOUGH_MEMORY.
Example: None

2.7 MTECSDK_ProcessDoc

This function sends a card personalization transaction with the specified options to the device with the specified name. When the device completes the transaction, the result is returned in pcDocInfo.
ULONG MTECSDK_ProcessDoc ( char *pcDevName, char *pcProcessOptions, char *pcDocInfo, DWORD *pdwDocInfoSize );
For every card personalization transaction, the EC2000 requires a new set of options detailing how the card will be personalized (image files, text lines, magnetic stripe data, embosser data, and so on). The options are stored as key-value pairs in the buffer pointed to by pcProcessOptions.
Parameters: pcDevName - Pointer to a null-terminated string containing device name. pcProcessOptions - Pointer to a buffer containing the options to be used in processing the card. The options are stored in the buffer by using function MTECSDK_SetValue. pcDocInfo - Pointer to the buffer containing the information returned from the device. The returned information contains Command status, MagnePrint data, Magstripe data, Smartcard data, and Device status information. pdwDocInfoSize - Size of the buffer pcDocInfo.
Return Values: EC_ST_OK EC_ST_NOT_ENOUGH_MEMORY EC_ST_PROCESS_CARD_FAILED EC_ST_BAD_DATA EC_ST_BAD_BUFFER EC_ST_BAD_BUFFER_LENGTH EC_ST_BAD_DEVICE_NAME EC_ST_DEVICE_NOT_OPEN EC_ST_DEVICE_NOT_RESPONDING EC_ST_REQUEST_TIMEDOUT EC_ST_CONNECT_REQUEST_TIMEDOUT EC_ST_ERR_INTERNET_CONNECT EC_ST_ERR_HTTP_OPEN_REQUEST EC_ST_ERR_HTTP_SEND_REQUEST
Remarks: If the function succeeds, the return value is EC_ST_OK.
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 15 of 21
2 - Functions
If there is no data returned from device, the return value is EC_ST_PROCESS_DOC_FAILED. If pcProcessOptions is NULL, the return value is EC_ST_BAD_DATA. If pcDocInfo is NULL, the return value is EC_ST_BAD_BUFFER. If the size of returned data is larger than the value specified in pdwDocInfoSize, the return value is EC_ST_NOT_ENOUGH_MEMORY. If there is a bad connection with the device, the return value will be one of the following: EC_ST_CONNECT_REQUEST_TIMEDOUT EC_ST_REQUEST_TIMEDOUT EC_ST_DEVICE_NOT_RESPONDING EC_ST_ERR_INTERNET_CONNECT EC_ST_ERR_HTTP_OPEN_REQUEST EC_ST_ERR_HTTP_SEND_REQUEST
Example:
#define BUFFER_LEN 4096
char docInfo [BUFFER_LEN]; char options [BUFFER_LEN]; char Device[4096] =""; DWORD docInfoSize;;
// Set up options using function MTECSDK_SetValue // Use function MTECSDK_GetDevice to get device name for variable “Device”
docInfoSize = BUFFER_LEN; dwStatus=MTECSDK_ProcessDoc(Device, options, docInfo, &docInfoSize);
// Use MTECSDK_GetValue to parse the docInfo.

2.8 MTECSDK_GetValue

This function retrieves a key/value pair that was previously stored in the pcDocInfo parameter using MTECSDK_SetValue function.
ULONG MTECSDK_GetValue ( char *pcDocInfo, char *pcSection, char *pcKey, char *pcValue, DWORD *pdwLength );
Parameters: pcDocInfo - Buffer pointer containing all the 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 the buffer that receives the retrieved string. pdwLength - Specifies the size of the pcValue buffer.
Return Values:
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 16 of 21
2 - Functions
EC_ST_OK EC_ST_NOT_ENOUGH_MEMORY EC_ST_ERR_LOAD_XML EC_ST_ERR_GET_DOM_POINTER EC_ST_BAD_DATA EC_ST_BAD_SECTION_NAME EC_ST_BAD_KEY_NAME EC_ST_BAD_VALUE_BUFFER EC_ST_BAD_BUFFER_LENGTH EC_ST_KEY_NOT_FOUND
Remarks: MTECSDK_GetValue finds the key in the pcDocInfo buffer then returns its value in pcValue. If MTECSDK_GetValue succeeds it returns EC_ST_OK.
If pdwLength is less than the size of the returned value, the function returns EC_ST_NOT_ENOUGH_MEMORY and returns the required size of the pcValue buffer in pdwLength.
If the key/value pair can not be found, pcValue will be NULL and the function will return EC_ST_KEY_NOT_FOUND.
Example:
char Settings [4096]; char DocInfo [4096]; char device[4096] =""; DWORD SettingsBufferSize; DWORD DocInfoSize; char cValue [1024]; DWORD valueSize; DWORD dwStatus;
// Initialize Settings
DocInfoSize = 4096;
// Use function MTECSDK_GetDevice to get // device name for variable “device” // Call MTECSDK_ProcessDoc function to process a document. dwStatus = MTECSDK_ProcessDoc (device, Settings, DocInfo, &DocInfoSize);
if (dwStatus == MTEC_ST_OK) {
// Check the return status from the device valueSize = 1024; dwStatus=MTECSDK_GetValue(DocInfo, "CommandStatus", "ReturnCode", cValue, &valueSize); if (dwStatus != EC_ST_OK) // error retrieving key value else
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 17 of 21
2 - Functions
{ // do further process } }

2.9 MTECSDK_GetAttribute

This function reads the buffer specified by pcDocInfo to retrieve an attribute from the XML tag specified by pcSection and pcKey (for example, it can read the id attribute from the tag <mytag id=5>.
ULONG MTECSDK_GetAttribute ( char *pcDocInfo, char *pcSection, char *pcKey, char *pcValue, DWORD *pdwLength );
Parameters: pcDocInfo - Buffer pointer containing all the 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 the buffer that receives the retrieved string. pdwLength - Specifies the size of the pcAttribute buffer.
Return Values: EC_ST_OK EC_ST_NOT_ENOUGH_MEMORY EC_ST_ERR_LOAD_XML EC_ST_ERR_GET_DOM_POINTER EC_ST_BAD_DATA EC_ST_BAD_SECTION_NAME EC_ST_BAD_KEY_NAME EC_ST_BAD_VALUE_BUFFER EC_ST_BAD_BUFFER_LENGTH EC_ST_KEY_NOT_FOUND
Remarks: MTECSDK_GetAttribute finds the key in the pcDocInfo buffer then returns its value in pcValue. If the function succeeds it returns EC_ST_OK.
If pdwLength is less than the size of the returned value, the function returns EC_ST_NOT_ENOUGH_MEMORY and returns the required size for the pcValue buffer is in the pdwLength.
If the key/value pair can not be found, pcValue is null and the function returns EC_ST_KEY_NOT_FOUND.
Example:
char Settings [4096];
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 18 of 21
2 - Functions
char DocInfo [4096]; char device[4096] =""; DWORD SettingsBufferSize; DWORD DocInfoSize; char cValue [1024]; DWORD valueSize; DWORD dwStatus;
// Initialize Settings
DocInfoSize = 4096;
// Use function MTECSDK_GetDevice to get // device name for variable “device” // Call MTECSDK_ProcessDoc function to process a document. dwStatus = MTECSDK_ProcessDoc (device, Settings, DocInfo, &DocInfoSize);
if (dwStatus == MTEC_ST_OK) {
// Check the return status from the device valueSize = 1024; dwStatus=MTECSDK_GetValue(DocInfo, "CommandStatus", "ReturnCode", cValue, &valueSize); if (dwStatus != EC_ST_OK) // error retrieving key value else { // do further process } }

2.10 MTECSDK_QueryInfo

This function sends a DeviceInformation request to the device specified by pcDevName, and returns the contents of the section specified by pcSection.
ULONG MTECSDK_QueryInfo ( char *pcDevName, char *pcSection, char *pcSectionData, DWORD *pdwLength );
Parameters: pcDevName - Pointer to null-terminated string containing device name. pcSection - Pointer to null-terminated string containing the desired section to return from the DeviceInformation request. Details about DeviceInformation requests can be found in 99875611 ExpressCard 2000 Programmer’s Reference (XML), available from MagTek. pcSectionData - Pointer to the buffer that is used to store the contents of the requested section.
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 19 of 21
2 - Functions
pdwLength - Specifies the size of the pcSectionData buffer.
Return Values: EC_ST_OK EC_ST_DEVICE_NOT_OPEN EC_ST_DEVICE_NOT_RESPONDING EC_ST_DEVICE_CONNECTION_ERROR EC_ST_REQUEST_TIMEDOUT EC_ST_CONNECT_REQUEST_TIMEDOUT EC_ST_ERR_INTERNET_CONNECT EC_ST_ERR_HTTP_OPEN_REQUEST EC_ST_ERR_HTTP_SEND_REQUEST EC_ST_NOT_ENOUGH_MEMORY EC_ST_BAD_DEVICE_NAME EC_ST_BAD_QUERY_PARM EC_ST_BAD_BUFFER EC_ST_BAD_BUFFER_LENGTH
Remarks: If the function succeeds it returns EC_ST_OK. If the device fails to respond, the function returns EC_ST_DEVICE_NOT_RESPONDING. If the memory allocated for pcSectionData buffer is not large enough to store the data of the inquiry section, the function returns EC_ST_NOT_ENOUGH_MEMORY.
If there is a bad connection with the device, the return value will be one of the following: EC_ST_CONNECT_REQUEST_TIMEDOUT EC_ST_REQUEST_TIMEDOUT EC_ST_DEVICE_NOT_RESPONDING EC_ST_ERR_INTERNET_CONNECT EC_ST_ERR_HTTP_OPEN_REQUEST EC_ST_ERR_HTTP_SEND_REQUEST
Example:
#define BUFFER_LEN 4096 char pResult [BUFFER_LEN]; DWORD resultLength; resultLength = BUFFER_LEN; MTECSDK_QueryInfo(pcDeviceName, "DeviceCapabilities",pResult,&resultLength);

2.11 MTECSDK_SendCommand

This function sends a single command to the device with the specified device name. It is not supported.

2.12 MTECSDK_CloseDevice

This function closes device with the specified device name.
ULONG MTECSDK_CloseDevice ( char *pcDevName );
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 20 of 21
2 - Functions
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 MTECSDK_OpenDevice.
Return Values: EC_ST_OK EC_ST_BAD_DEVICE_NAME EC_ST_DEVICE_NOT_FOUND
Remarks: If the pcDevName is NULL, the return value is EC_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 = MTECSDK_GetDevice(i,(char*) pcDevName)) != EC_ST_DEVICE_NOT_FOUND) { // Success in getting the device name // Open this device if (MTECSDK_OpenDevice (pcDevName) == EC_ST_OK) { // Now close this device MTECSDK_CloseDevice (pcDevName); } else { // Error while opening this device. }
i++; }
ExpressCard 2000| Instant Issuance Card Personalization System | Programmer’s Reference (Windows SDK)
Page 21 of 21
Loading...