All pages
Powered by GitBook
1 of 9

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Introduction

This document provides instructions for software developers who want to create Windows C++ software solutions that include a MagTek Common Message Structure (MTCMS) device connected to a Windows PC.

How to Set Up the MagTek CMS SDK for Windows C++ Projects

To add the MagTek CMS libraries to a Windows C++ project in Microsoft Visual Studio, follow these steps:

  • Create or open your project in Visual Studio.

  • Copy the following DLL file from the MTCMSDemo folders to the library folder of your software project:

    • MTCMS.dll

  • In the Visual Studio Solution Explorer, right-click the project and select Add Reference to show the Add Reference window.

  • Select the Browse tab and press the Browse… button.

  • Navigate to your library folder, select MTCMS.dll, then press the Add button.

  • In your custom software, create an instance of MTDevice. For examples, see the source code included with the MTCMSDemo project and/or Appendix A Code Examples.

  • Begin using the features provided by the MTCMS library

About MTCMS Library

Custom Windows software installed on a host PC can communicate with MagTek Common Message Structure (MTCMS) devices via USB, network interface, or serial interface using the MTCMS library.

The supported platforms for Windows C++ projects include Windows 7, Windows 8/8.1, and Windows 10. The Windows C++ project should contain references to the main library file: MTCMS.dll.

Common Message Structure (MTCMS) Programmer’s Reference Manual (C++)

Manual Part Number: D998200159-10 REGISTERED TO ISO 9001:2015 MagTek I 1710 Apollo Court I Seal Beach, CA 90740 I Phone: (562) 546-6400 I Technical Support: (888) 624-8350 www.magtek.com Copyright © 2006-2018 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. 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

Rev Number

Date

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 ADDRESS ON THE FRONT PAGE OF THIS DOCUMENT, 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 ADDRESS LISTED IN THIS DOCUMENT, OR E-MAILED TO SUPPORT@MAGTEK.COM.

Appendix A Code Examples

Notes

10

05/25/2018

Initial Release

Connect to Device

Send Command String to Device

Send Command Bytes to Device

Send MTCMSMessage to Device

Receiving Connection State Updates from Device

Receiving Response Message from Device

Receiving Notification Message from Device

Close Device

openDevice();
const char* dataString = “C00101C10100C20114”; 
sendDataString(dataString);
unsigned char* dataBytes =
{0xC0,0x01,0x01,0xC1,0x01,0x00,0xC2,0x01,0x14};

sendDataBytes(dataBytes,9);
MTCMSMessage* message = CreateMTCMSMessage(0x01,0x00,0x14, NULL,0, 
false);
sendMTCMSMessage(message); 
ReleaseMTCMSMessage(message);
void _stdcall OnDeviceConnectionStateChanged(void* sender, 
MTConnectionState state)
{
        switch (state)
        {
        case MTConnectionState::Connected: 
                Log(_T("[Connected]")); 
                break;
        case MTConnectionState::Connecting: 
                Log(_T("[Connecting...]")); 
                break;
        case MTConnectionState::Disconnecting: 
                Log(_T("[Disconnecting...]")); 
                break;
        case MTConnectionState::Disconnected: 
                Log(_T("[Disconnected]")); 
                break;
        }
}
void  stdcall OnDeviceResponseMessage(void* sender, const 
MTCMSMessage* response)
{
    processResponseMessage(response);
}
void  stdcall OnDeviceNotificationMessage(void* sender, const 
MTCMSMessage* notification)
{
    processNotificationMessage(notification);
}
closeDevice();

MTDevice Events

OnDeviceList

The library will call this function when device information is available.

typedef void ( stdcall * OnDeviceListEvent)( 
void* sender,
MTConnectionType connectionType, 
int deviceCount, 
MTDeviceInformation* deviceList);

Parameter

Description

sender

Object representing the publisher of the event.

connectionType

Return Value: None

This event occurs when the connection state of the device is changed.

This event occurs when a response is received from the device.

Return Value: None

This event occurs when a response is received from the device.

This event occurs when a response is received from the device.

MTCMSMessage Structure

These methods allows building CMS messages to be used in communications with MagTek CMS devices.

This constructor method builds an MTCMSMessage instance with the provided values.

Parameters:

MTConnectionType value: MTConnectionType.USB, MTConnectionType.IP, MTConnectionType.Serial

deviceCount

Number of devices in deviceList.

deviceList

A list of MTDeviceInformation objects.

Parameter

Description

sender

Object representing the publisher of the event.

state

MTConnectionState value indicating the state of the device: MTConnectionState.Disconnected MTConnectionState.Connecting MTConnectionState.Error MTConnectionState.Connected MTConnectionState.Disconnecting

Parameter

Description

sender

Object representing the publisher of the event.

dataString

String representing data received.

Parameter

Description

sender

Object representing the publisher of the event.

response

MTCMSMessage representing data received.

Parameter

Description

sender

Object representing the publisher of the event.

notification

MTCMSMessage representing data received.

OnDeviceConnectionStateChanged

OnDeviceDataString

OnDeviceResponseMessage

OnDeviceNotificationMessage

MTCMS Library Enumerations and Structures

The MTCMS Library uses the following constants and data structures.

MTConnectionType Values

Device connection types:

MTConnectionState Values

Device connection states:

MTDeviceInformation

Device information structure:

MTCMSMessage

MTCMSMessage structure:

typedef void ( stdcall * OnDeviceConnectionStateChangedEvent)( 
void* sender,
MTConnectionState state);
typedef void ( stdcall * OnDeviceDataStringEvent)( 
void* sender, 
const char* dataString);
typedef void ( stdcall * OnDeviceResponseMessageEvent)( void* sender,
const MTCMSMessage* response);
typedef void ( stdcall * OnDeviceNotificationMessageEvent)( 
void* sender,
const MTCMSMessage* notification);
enum MTConnectionType
{
        USB, IP,
                Serial
};
enum MTConnectionState
{
    Disconnected, 
    Connecting,
    Error, 
    Connected, 
    Disconnecting
};
struct MTDeviceInformation
{
    const char* Id; 
    const char* Name; 
    const char* Address;
    const char* ProductId;
};
struct MTCMSMessage
{
    int messageType; 
    int applicationID; 
    int commandID;
    int resultCode; 
    int dataTag;
    const unsigned char* data; 
    int dataLength;
    const unsigned char* messageBytes; 
    int messageBytesLength;
};

applicationID

ApplicationID value

commandID

CommandID value

dataTag

Data tag value

data

Data value

dataLength

Length of data value

Return Value: MTCMSMessage structure

This constructor method builds an MTCMSMessage instance with the provided values.

Parameters:

Parameter

Description

messageBytes

Message in byte array value

messageBytesLength

Length of message bytes value

Return Value: MTCMSMessage structure

This constructor method builds an MTCMSMessage instance with the provided values.

Parameters:

Parameter

Description

applicationID

ApplicationID value

commandID

CommandID value

dataTag

Data tag value

Return Value: MTCMSMessage structure

This method releases the resource allocated by calls to CreateMTCMSMessage and CreateMTCMSRequestMessage methods.

Parameters:

Parameter

Description

message

MTCMSMessage to deallocate.

Return Value: None

MTCMS_API MTCMSMessage* CreateMTCMSMessage( 
int messageType,
int applicationID, 
int commandID,
int dataTag,
const unsigned char* data, 
int dataLength);

Parameter

Description

messageType

CreateMTCMSMessage

MessageType value

MTCMS_API MTCMSMessage* CreateMTCMSMessageFromBytes( 
const unsigned char* messageBytes,
int messageBytesLength);
MTCMS_API MTCMSMessage* MTCMSMessage( 
int applicationID,
int commandID,
int dataTag,
const unsigned char* data, 
int dataLength);
MTCMS_API void ReleaseMTCMSMessage(MTCMSMessage* message);

CreateMTCMSMessageFromBytes

CreateMTCMSRequestMessage

ReleaseMTCMSRequestMessage

data

Data value

dataLength

Length of data value

MTCMS Class Methods

After creating an instance of the MTCMS class in your software project, use the methods described in this section to communicate with MagTek CMS device.

requestDeviceList

This method initiates request to discover devices that are visible to the host using the specified connection interface. The DeviceListReceived event will provide information regarding the available devices once the discovery process is completed.

MTCMS_API void requestDeviceList(MTConnectionType connectionType); Parameters:

Parameters:

Parameter

Description

Return Value: None

This method sets the connection type of the device..

Parameters

Return Value: None

This method sets the address of the device.

Parameters:

The following table shows the address formats supported by the different connection types:

Return Value: None

This method sets the device ID.

Return Value: None

This method opens the connection to the device.

Parameters: None

Return Value: None

This method closes the connection to the device.

Parameters: None Return Value: None

This method returns whether the device is connected or not.

Parameters: None

Return Value:

Return true if the device is connected. Otherwise, return false.

This method sends a command string to the device.

Parameters:

Return Value:

  • 0 = Success

  • 9 = Error

  • 15 = Busy

This method sends a command to the device.

Parameters:

Return Value:

  • 0 = Success

  • 9 = Error

  • 15 = Busy

This method sends a command to the device.

Parameters:

Return Value:

  • 0 = Success

  • 9 = Error

  • 15 = Busy

IP

[PORT]

The TCP port of the device. (Default: 5000)

Serial

[DATABITS]

The data bits per byte. (Default: 8)

Serial

[PARITY]

The parity checking protocol. (Default: NONE).

Supported Values: NONE,EVEN,ODD,SPACE,MARK

Serial

[STOPBITS]

The number of stop bits per byte. (Default: 1)

Supported Values: 1,1.5,2

Serial

[HANDSHAKE]

The handshaking protocol for serial port transmission of data. (Default: NONE)

Supported Values: NONE,RTS,XONXOFF,RTSXONSOFF

Serial

[STARTINGBYTE]

The special character used as the starting byte for each message. (Default is empty string)

An empty string indicates no special character is used as the starting byte for each message.

Serial

[ENDINGBYTE]

The special character used as the ending byte for each message. (Default is 0x0A)

Serial

An empty string indicates no special character is used as the ending byte for each message.

Serial

[CRCMODE]

A value of 0 indicates CRC is disabled, otherwise CRC is enabled. (Default: 0)

connectionType

MTConnectionType value: MTConnectionType.USB, MTConnectionType.IP, MTConnectionType.Serial

Parameter

Description

connectionType

MTConnectionType value: MTConnectionType.USB, MTConnectionType.IP, MTConnectionType.Serial

Parameter

Description

deviceAddress

String value of the address.

Connection Type

Address Format Parameter

Address Format Description

USB

[PATH]

The OS specific device path to the USB device. The path is normally retrieved from the Address property of MTDeviceInformation.

IP

[IPA]

Connection Type

Address Format

Serial

PORT=[PORT],

BAUDRATE=[BAUDRATE],

DATABITS=[DATABITS],

PARITY=[PARITY],

STOPBITS=[STOPBITS],

HANDSHAKE=[HANDSHAKE],

STARTINGBYTE=[STARTINGBYTE],

ENDINGBYTE=[ENDINGBYTE],

CRCMODE=[CRCMODE]

Connection Type

Parameter

Description

Serial

[PORT]

The OS specific device path to the serial port (i.e. COM4).

Serial

[BAUDRATE]

Parameter

Description

deviceID

String value of the device ID.

Parameter

Description

dataString

Command to be sent in hexadecimal string format.

Parameter

Description

dataBytes

Command to be sent in byte array format.

dataBytesLength

Length of the command bytes.

Parameter

Description

message

MTCMSMessage to be sent to the device.

setConnectionType

setAddress

setDeviceID

openDevice

closeDevice

isDeviceConnected

sendDataString

sendDataBytes

sendMTCMSMessage

The IP address of the device in dotted-quad notation (i.e. 192.178.1.123).

The data baud rate . (Default: 9600)

MTCMS_API void setConnectionType(MTConnectionType connectionType); 
MTCMS_API void setAddress(const char* deviceAddress);
MTCMS_API void setDeviceID(const char* deviceID); 
MTCMS_API void openDevice(); 
MTCMS_API void closeDevice();
MTCMS_API bool isDeviceConnected();
MTCMS_API int sendCommandString(const char* dataString);
MTCMS_API int sendDataBytes( 
const unsigned char* dataBytes, 
int dataBytesLength);
MTCMS_API int sendMTCMSMessage(MTCMSMessage* message);