MagTek EC2000 99875713 User Manual

ExpressCard 2000

Instant Issuance Card Personalization System

Programmer’s Reference (Windows SDK)

August 2014

Manual Part Number:

99875713-1.01

REGISTERED TO ISO 9001:2008

MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: [phone] I Technical Support: [phone]

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