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: (562) 546-6400 I Technical Support: (888) 624-8350 www.magtek.
0 - Table of Contents 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.
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.
1 - Table of Contents Table of Contents Table of Contents ............................................................................................................................... 4 1 2 Introduction ................................................................................................................................. 5 1.1 Product Summary ............................................................................................................... 5 1.
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 - Introduction 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.
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.
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.
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.
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.
2 - Functions ); Parameters: hFileHandle - File handle. All the API functions will log messages and errors to this log file. Return Values: None. Remarks: None.
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.
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.
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.
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.
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.
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 . ULONG MTECSDK_GetAttribute ( char *pcDocInfo, char *pcSection, char *pcKey, char *pcValue, DWORD *pdwLength ); Parameters: pcDocInfo - Buffer pointer containing all the key/value pairs.
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.
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.
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.
