MDBEngine API programming manual.

Contents

Introduction

General API function calls

    Target firmware download

Reader... API function calls

    Reader initialization

    Message dispatcher

    Reader enable

    Transaction sequence

Introduction

This programming manual explains the MDBEngine DLL API interface. The MDBEngine DLL is designed for Microsoft Windows supporting USB.

General API function calls

The general API calls are used to download the target firmware and to retrieve information about the MDBEngine DLL.

General API function call references.

Target firmware download

The target firmware must be downloaded do the USB / MDB interface prior to any other function calls.This call should be in a very early stage of the application.  

The target firmware download function call 'DownloadTarget()' should be inside the 'InitInstance' of your application. The target firmware is located inside the resources of the DLL.

Sample:

if (!DownloadTarget(0))
{
    return false;
}

Reader... API function calls

The MDBEngine is MDB master and addresses a debit card reader. The calls: Reader... are used to control the debit card reader. Whenever the MDBEngine needs to inform the application about any state change it sends a windows message WM_READER_STATUS whereas wParam contains the actual status. The application uses the Reader... API calls to retrieve the requested information.

Reader... API function call reference.

Reader initialization

The 'CreateReader' call is the second step after download of the target firmware. This call should be in a very late stage of the appliaction. Fill in the SLAVE_SETUP structure and call 'ReaderCreate'.

The reader initialization sequence is like:

SLAVE_SETUP Setup;
memset(&Setup,0,sizeof(SLAVE_SETUP));
Setup.lParam=(LPARAM)this;
Setup.hParent=m_hWnd;
Setup.dwTimeout=5;
if (!ReaderCreate(&Setup))
{
    TRACE(_T("Failed to create reader\r\n"));

    return false;
}
return true;

Message dispatcher

Whenever there is some information for your application, a message WM_READER_STATUS is send where wParam contains the message status. With Visual C++ design a message dispatcher like below and write a function for each case.

Function prototype:

afx_msg void OnStatusChange(WPARAM wParam, LPARAM lParam);

Message map:

ON_MESSAGE(WM_READER_STATUS, OnStatusChange)

Message dispatcher:

void CReader::OnStatusChange(WPARAM wParam, LPARAM lParam)
{
    switch (wParam)
    {
        case SS_READER_READY:

        {

            // Reader is ready after reset or powerup.

            break;

        }

        case SS_READER_ENABLE:
        {
            // Reader was enabled.
            break;
        }
        case SS_READER_DISABLE:
        {
            // Reader was disabled.
            break;
        }
        case SS_READER_BEGIN_SESSION:
        {

            // Card present, retrive data.
            break;
        }
        case SS_READER_END_SESSION:
        {
            // Card removed.
            break;
        }
        case SS_READER_APPROVED:
        {
            // Current vend approved.
            break;
        }
        case SS_READER_REVALUE_APPROVED:
        {
            // Revalue approved.
            break;
        }
    }
}

Reader enable

Use the function call 'ReaderEnable(BOOL)' to Enable or disable the reader, acording your application accept or ignore the presented debit card.

Transaction sequence

A normal transaction (debit the card) has following sequenze:

• Wait for the SS_READER_BEGIN_SESSION message to have a card presented.
• Call 'ReaderVendRequest(pRequest)' with item amount and item number.
• Wait for the SS_READER_APPROVED message to finalize the transaction.
• Or wait for the SS_READER_DENIED message if there is not enought credit.
• Call 'ReaderVendStatus(READER_VEND_SUCCESS)' to confirm the transaction.
• Or call 'ReaderVendStatus(READER_VEND_FAILED)' to cancel the transaction.
• Wait for the SS_READER_SUCCESS message for the confirmation of the transaction.
• Call 'ReaderSessionComplete()' to finish the transaction.

[Home] - Copyright © 2002-2003  by BonusData AG, webmaster@bonusdata.net. Last update: 23.07.2003