Reader... MDBEngine API programming reference.


Contents

Introduction

ReaderCreate

ReaderDestroy

ReaderReset

ReaderEnable

ReaderInfo

ReaderSession

ReaderSessionComplete

ReaderDisplay

ReaderVendRequest

ReaderVendStatus

ReaderRevalueRequest

ReaderRevalueLimit

ReaderFeatureEnable

Introduction

The function calls of this section apply to the debit card reader control. This calls will fail until the function call ReaderCreate returned TRUE.

If a function call returns FALSE you may use the Windows API call 'GetLastError()' to retrieve more information on the error.

To fully understand this API a basic knowledge of the MDB protocol and it's specification is recommended.

ReaderCreate

This function call it the first to call before any of the other calls is ready to be used. It creates and initializes the debit card reader API.

extern "C" BOOL WINAPI ReaderCreate(SLAVE_SETUP* pSetup);

Parameters:

    pSetup

        [IN] Setup parameter for the debit card reader. See structure below.

Return value:

    TRUE on success.

Note: Fill in the SLAVE_SETUP structure and pass it with this function call.

Structure of slave setup:

typedef struct tag_SLAVE_SETUP
{
    LPARAM lParam;
    HWND hParent;
    DWORD dwDevice;
    DWORD dwTimeout;
    DWORD dwInterval;
    DWORD dwMaxRetry;
    DWORD dwMaxFail;
    DWORD dwFeatureLevel;
    DWORD dwScalingFactor;
    DWORD dwDisplayColumns;
    DWORD dwDisplayRows;
    DWORD dwDisplayType;
    DWORD dwMinimumPrice;
    DWORD dwMaximumPrice;
}
SLAVE_SETUP;

Note:

All the other function calls will fail if used prior to this call.

ReaderDestroy

Use this call to destroy the debit card reader API. This call is important and must be made before closing the application.

extern "C" BOOL WINAPI ReaderDestroy();

Parameters:

    None:

Return value:

    TRUE on success.

ReaderReset

Reset the MDB debit card reader device by sending a reset command.

extern "C" BOOL WINAPI ReaderReset();

Parameters:

    None:

Return value:

    TRUE on success.

Note:

This call will reset the debit card reader state machine of MDBEngine and force a new initialization sequence of the connected MDB debit card reader.

At the end of the initialization sequence a message with SS_READER_READY will be send.

After initialization the debit card reader is disabled.

ReaderEnable

Enable or disable the connected debit card reader. The reader will accept cards in enabled state only.

extern "C" BOOL WINAPI ReaderEnable(BOOL bEnable);

Parameters:

    bEnable

[IN] TRUE to enable the debit card reader and accept debit cards. FALSE to refuse debit cards.

Return value:

    TRUE on success.

ReaderInfo

Retrieve all available information of the connected debit card reader.

extern "C" BOOL WINAPI ReaderInfo(READER_INFO* pInfo);

Parameters:

    pInfo

[OUT] Structure with the information supplied by the debit card reader. See structure below.

Return value:

    TRUE on success.

Structure of reader info:

typedef struct tag_READER_INFO
{
    DWORD dwFeatureLevel;
    DWORD dwCountryCode;
    DWORD dwScalingFactor;
    DWORD dwDecimalPlaces;
    DWORD dwResponseTime;
    DWORD dwMiscOptions;
    DWORD dwOptionalFeatures;
    char sManufacturer[MAX_MANUFACTURER+1];
    char sSerialNumber[MAX_SERIAL_NUMBER+1];
    char sModelNumber[MAX_MODEL_NUMBER+1];
    WORD wVersion;
}
READER_INFO;

Note:

Depending on the reader type, not all of the supplied card reader info is available or relevant.

ReaderSession

Used to retrieve the session info.

extern "C" BOOL WINAPI ReaderSession(READER_SESSION* pSession);

Parameters:

    pSession

        [OUT] Session information as supplied by begin session of the debit card reader.

Return value:

    TRUE on success.

Structure of reader session:

typedef struct tag_READER_SESSION
{
    DWORD dwFunds;
    DWORD dwMediaID;
    DWORD dwPaymentType;
    DWORD dwPaymentData;
    DWORD dwLanguage;
    DWORD dwCurrency;
    DWORD dwOptions;
}
READER_SESSION;

Note:

A call to ReaderSession is valid only after a message with SS_READER_BEGIN_SESSION is received.

ReaderSessionComplete

Used to complete and leave the current session.

extern "C" BOOL WINAPI ReaderSessionComplete();

Parameters:

    None:

Return value:

    TRUE on success.

Note:

This function call is available while inside an active session.

ReaderDisplay

Retrieve display information after received a SS_READER_DISPLAY_REQUEST message.

extern "C" BOOL WINAPI ReaderDisplay(READER_DISPLAY* pDisplay);

Parameters:

    pDisplay

        [OUT] Display information of the debit card reader display request. See structure below.

Return value:

    TRUE on success.

Reader display structure:

typedef struct tag_READER_DISPLAY
{
    DWORD dwDisplayTime;
    char pDisplayData[MAX_DISPLAY_DATA];
}
READER_DISPLAY;

Note:

The debit card reader may request to display some information on the display of the MDB master. This call is used after the SS_READER_DISPLAY_REQUEST message.

ReaderVendRequest

Request the debit card reader to start a vend cycle.

extern "C" BOOL WINAPI ReaderVendRequest(READER_REQUEST* pRequest);

Parameters:

    [IN] Vend request data. See structure below.

Return value:

    TRUE on success.

Vend request structure:

typedef struct tag_READER_REQUEST
{
    DWORD dwItemPrice;
    DWORD dwItemNumber;
}
READER_REQUEST;

Note:

This function call is valid inside an active session.

ReaderVendStatus

Used to confirm the current vend cycle.

extern "C" BOOL WINAPI ReaderVendStatus(DWORD dwStatus);

Parameters:

    dwStatus

        [IN] Reply with READER_VEND_SUCCESS to confirm the current vend cycle.

        [IN] Reply with READER_VEND_FAILURE to undo the current vend cycle.

        [IN] Reply with READER_VEND_CANCEL to abort the current vend cycle.

Return value:

    TRUE on success.

Note:

Reply with this call after receiption of the SS_READER_APPROVED message. This will definitive settle the current transaction.

ReaderRevalueRequest

Used to issue a revalue request to the debit card reader.

extern "C" BOOL WINAPI ReaderRevalueRequest(DWORD dwAmount);

Parameters:

    dwAmount

        [IN] Amount to revalue.

Return value:

    TRUE on success.

Note:

This command is valid inside an active session only.

ReaderRevalueLimit

Used to retrieve the maximum allowed revalue amount.

extern "C" BOOL WINAPI ReaderRevalueLimit(DWORD* pdwLimit);

Parameters:

    pdwLimit

        [OUT] Maximum allowed revalue amount.

Return value:

    TRUE on success.

Note:

This command is valid inside an active session only. Normally this function call is used prior to a ReaderRevalueRequest to avoid a revalue denied condition.

ReaderFeatureEnable

Used to enable reader specific features if available.

extern "C" BOOL WINAPI ReaderFeatureEnable(DWORD dwFeatures);

Parameters:

    [IN] Feature option bits.

Return value:

    TRUE on success.

Note:

This function call is valid on level 3 or higher reader implementations. The reader feature level and available options can be retrieved with a call to ReaderInfo. Enable additional reader feature prior to ReaderEnable.


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