C++ Library

📘
What is an API function?
An API functions with the goal of allowing different systems, applications and devices to share information with each other. APIs work by translating a user's input into data, which helps a system send back the right response

In the section you may find multiples appendixes. Each of these refer to a different set of information need for implementing POS buddy using the C++ library.

On this page you will find the below sections relating to POS Buddy C++ library:

Appendix A : Data types
Appendix B: Windows Implementation
Appendix C:: Linux Implementation.

API Functions

Below is a list of the API functions and their descriptions that is found inside the POS Buddy C++ library.**

PosBuddyInterface* PosBuddyInterface::create()
Creates an instance of PosBuddy.
pbResult setComms(commsType type)
Set comms interface to use, e.g. serial port, USB or Websocket.
pbResult setMerchantId(string merchantId)
Set the Merchant ID.
Needed for transacting.
pbResult setUsername(string username)
Set the Username.
Only needed for normal auth calls.
pbResult setApplicationKey(string applicationKey)
Set the Application Key.
Needed for transacting.
pbResult setAuthenticationKey(string authenticationKey)
Set the Authentication Key.
Needed for transacting.
pbResult setBarcodeCallback(void (*callback)(string barcode))
Set the callback function when a barcode is scanned using the device's internal barcode scanner.
The callback function will return a string containing the scanned barcode.

// Example code

// Callback function
void barcodeReceived(string barcode) {
    cout << "Received barcode: " << barcode << endl;
}

posBuddy->setBarcodeCallback(barcodeReceived);

pbResult pingDevice(void (*callback)(map<string, string> resultMap))
Sends a PING request to the device and verifies if it receives a reply back.
This is used to verify low level communications are working and to retrieve information about the device, e.g. device type and serial number.

Possible return values:
COMMS_ERROR
NO_RESPONSE
INVALID_RESPONSE
RESULT_OK

// Format of callback function:
void pingCallback(map<string, string> resultMap)

pbResult getInfo(void (*callback)(map<string, string> resultMap))
Retrieve information about the device.

pbResult clearItems()
Clear the items on the line display of the terminal and show the logo screen

Possible return values:
SALE_IN_PROGRESS
RESULT_OK

// Format of callback function:
void displayItemsCallback(map<string, string> resultMap)

pbResult doAuth(void (*callback)(map<string, string> resultMap))
Do an auth on the terminal. The terminal will prompt for the user password before it goes online. The authentication key will be returned in the callback function inside the resultMap with key: 'authenticationKey'.
The software needs to send this authentication key to the device using setAuthenticationKey() before a transaction can be initiated

Possible return values:
SALE_IN_PROGRESS
COMMS_ERROR
NO_RESPONSE
INVALID_RESPONSE
MISSING_PARAMETERS
AUTH_ERROR
RESULT_OK

// Format of callback function:
void authCallback(map<string, string> resultMap)

pbResult doRetailAuth(string secretKey, string accessKey, void (*callback)(map<string, string> resultMap))
Do a retail auth. The terminal will not prompt for the user password.
The authentication key will be returned in the callback function inside the resultMap with key: 'authenticationKey'.
The software needs to send this authentication key to the device using setAuthenticationKey() before a transaction can be initiated.
For security the call is not send to the terminal, instead it is done from the DLL.

Note: the application needs internet access for this call to work.

Possible return values:
SALE_IN_PROGRESS
COMMS_ERROR
NO_RESPONSE
INVALID_RESPONSE
MISSING_PARAMETERS
AUTH_ERROR
RESULT_OK

// Format of callback function:
void authCallback(map<string, string> resultMap)

pbResult doSale(unsigned long amount, map<string, string> extraParametersMap, void (*callback)(map<string, string> resultMap))
Initiate a sale transaction. Extra parameters can be set in the parameterMap. See Extra Parameters for details.
The result is returned as a map of strings inside resultMap in the callback function after the sale is completed. See Thumbzup Companion API technical reference for more details on the parameters.

Note: this function can return RESULT_OK even if a sale was not successful. The result of the sale transaction is from the issuer / acquirer inside the resultMap (RC)

Possible return values:
SALE_IN_PROGRESS
COMMS_ERROR
NO_RESPONSE
INVALID_RESPONSE
MISSING_PARAMETERS
AUTH_ERROR
COMMS_NOT_INITIALISED
RESULT_OK

// Format of callback function:
void saleCallback(map<string, string> resultMap)

pbResult printSunmiCommands(vector<vector> commands, void (*callback)(map<string, string> resultMap))
Send a print command to PosBuddy using Sunmi commands.
The description of the commands can be found in the 'SUNMI Inbuilt Printer Developer Documentation', available on the Sunmi website.

// Example of printing using Sunmi commands
vector<vector<string>> commands;

commands.push_back({ "setAlignment", "1" });
commands.push_back({ "lineWrap", "2" });
commands.push_back({ "printQRCode", "Hello from PosBuddy", "5", "1" });
commands.push_back({ "setBold" });
commands.push_back({ "setFontSize", "32" });
commands.push_back({ "printText", "Hello World\n" });

posBuddy->printSunmiCommands(commands, printCallback);

// Format of callback function:
void saleCallback(map<string, string> resultMap)

Appendix A : Data Types

In this section we are focusing on the data types needed for implementing the POS Buddy application using the C++ library.
You may refer to the below code sample for a list of data types available in the implementation:

/**
 * @brief Type of comms to use
 *
 */
enum commsType {
    none,
    serial,
    usb,
    websocket
};

/**
 * @brief status of websocket
 *
 */
enum pbConnectStatus {
    STATUS_UNKNOWN,
    STATUS_CONNECTED,
    STATUS_DISCONNECTED,
    STATUS_ERROR
};

/**
 * @brief Return values for POS Buddy functions
 *
 */
enum pbResult {
    RESULT_OK = 0,
    NOT_SUPPORTED = -1000,
    MISSING_PARAMETERS = -1001,
    PARSE_JSON_ERROR = -1002,
    NO_RESPONSE = -1003,
    COMMS_ERROR = -1004,
    INVALID_RESPONSE = -1005,
    AUTH_ERROR = -1006,
    SALE_IN_PROGRESS = -1007,
    SERVER_COMMS_ERROR = -1008,

    COMMS_NOT_INITIALISED = -2000,
    ERROR_OPENING_SERIAL_PORT = -2001,
    ERROR_OPENING_WEBSOCKET = -2002,

    MEMORY_RESOURCE_ERROR = -10000
};

/**
 * @brief Items to use for line display
 *
 */
struct pbItem {
    std::string quantityString;    /*!< Quantity to display on device */
    std::string costString;        /*!< Cost to display on device */
    std::string descriptionString; /*!< Description to display on device */
    long quantity;                 /*!< Value is not used by device. It can be used to make internal calculations easier */
    long cost;                     /*!< Value is not used by device. It can be used to make internal calculations easier */
};

Appendix B: Windows Implementation.

📘
In this section you will find a setup guide for implementing the POS Buddy on a Windows based POS machine.

Below is a sample code for the C++ implementation using libposbuddy.dll in Windows.
A more advanced demo application is also available on request.

#include <windows.h>
#include <cstdlib>
#include <iostream>
#include <map>
#include <string>
#include <unistd.h>
#include "posbuddyinterface.h"

using namespace std;
PosBuddyInterface *posBuddy;
void showConnectionStatus(pbConnectStatus status);
void authCallback(map<string, string> resultMap);
pbConnectStatus currentStatus;

int main(int argc, char *argv[]) {
    map<string, string> returnedResultMap;
    string authenticationKey;

    // Set customer specific values
    string merchantId = "...";
    string username = "...";
    string applicationKey = "...";

    if (argc <= 2) {
        cout << "Please enter serial port or websocket to connect to, e.g. " << endl;
        cout << "   " << argv[0] << " -SERIAL COM13" << endl;
        cout << "   " << argv[0] << " -WS 123456" << endl;
        exit(1);
    }
    
    // Load the posBuddy dll
    HMODULE hdl = ::LoadLibrary("libposbuddy.dll");
    if (hdl == 0) {
        cout << "error loading libposbuddy.dll " << endl;
        exit(1);
    }

    srand(time(NULL));
    posBuddy = PosBuddyInterface::create();

    if (strncmp(argv[1], "-SERIAL", 7) == 0) {
        if (posBuddy->setComms(serial) != RESULT_OK) {
            cout << "Error opening serial port" << endl;
            exit(1);
        }
    }
    else if (strncmp(argv[1], "-WS", 3) == 0) {
        if (posBuddy->setComms(websocket) != RESULT_OK) {
            cout << "Error opening websocket to " << argv[2] << endl;
            exit(1);
        }
    }
    else {
        cout << "Invalid option: " << argv[1] << endl;
        exit(1);
    }
    
    posBuddy->connect(argv[2], &showConnectionStatus);

    posBuddy->clearItems();
    posBuddy->setMerchantId(merchantId);
    posBuddy->setUsername(username);
    posBuddy->setApplicationKey(applicationKey);
    
    while (currentStatus != STATUS_CONNECTED) {
        cout << "waiting for connection..." << endl;
        usleep(500000);
    }
    
    pbResult result = posBuddy->doAuth(authCallback);
    if (result != RESULT_OK) cout << "Auth error: " << result << endl;

    // Print received result values
    for (auto it : resultMap) {
        cout << it.first << " = " << it.second << endl;
    }
    
}

void showConnectionStatus(pbConnectStatus status) {
    switch (status) {
    case STATUS_UNKNOWN:
        cout << "New status: Unknown" << endl;
        break;
    case STATUS_CONNECTED:
        cout << "New status: Connected" << endl;
        break;
    case STATUS_DISCONNECTED:
        cout << "New status: Disconnected" << endl;
        break;
    case STATUS_ERROR:
        cout << "New status: Error" << endl;
        break;
    }
    
    currentStatus = status;
}

void authCallback(map<string, string> resultMap) {
    if (resultMap.find("authenticationKey") != resultMap.end()) {
        string authenticationKey = resultMap.at("authenticationKey");
        if (authenticationKey.length() > 5) saveAuthenticationKey(authenticationKey); // do not save 'null'
    }
}

Appendix C : Linux implementation

📘
In this section you will find a setup guide for implementing the POS Buddy on a Linux based POS machine.

Below is a sample code for C++ implementation using libposbuddy.a library in Linux.
A more advanced demo application is also available on request.

#include <sys/ioctl.h>
#include <cstdlib>
#include <iostream>
#include <map>
#include <string>
#include <unistd.h>
#include "posbuddyinterface.h"

using namespace std;
PosBuddyInterface *posBuddy;
void showConnectionStatus(pbConnectStatus status);
void authCallback(map<string, string> resultMap);
pbConnectStatus currentStatus;

int main(int argc, char *argv[]) {
    map<string, string> returnedResultMap;
    string authenticationKey;

    // Set customer specific values
    string merchantId = "...";
    string username = "...";
    string applicationKey = "...";

    if (argc <= 2) {
        cout << "Please enter serial port or websocket to connect to, e.g. " << endl;
        cout << "   " << argv[0] << " -SERIAL COM13" << endl;
        cout << "   " << argv[0] << " -WS 123456" << endl;
        exit(1);
    }
    
    srand(time(NULL));
    posBuddy = PosBuddyInterface::create();

    if (strncmp(argv[1], "-SERIAL", 7) == 0) {
        if (posBuddy->setComms(serial) != RESULT_OK) {
            cout << "Error opening serial port" << endl;
            exit(1);
        }
    }
    else if (strncmp(argv[1], "-WS", 3) == 0) {
        if (posBuddy->setComms(websocket) != RESULT_OK) {
            cout << "Error opening websocket to " << argv[2] << endl;
            exit(1);
        }
    }
    else {
        cout << "Invalid option: " << argv[1] << endl;
        exit(1);
    }

    posBuddy->connect(argv[2], &showConnectionStatus);

    posBuddy->clearItems();
    posBuddy->setMerchantId(merchantId);
    posBuddy->setUsername(username);
    posBuddy->setApplicationKey(applicationKey);
    
    while (currentStatus != STATUS_CONNECTED) {
        cout << "waiting for connection..." << endl;
        usleep(500000);
    }

    pbResult result = posBuddy->doAuth(authCallback);
    if (result != RESULT_OK) cout << "Auth error: " << result << endl;

    // Print received result values
    for (auto it : resultMap) {
        cout << it.first << " = " << it.second << endl;
    }
    
}

void showConnectionStatus(pbConnectStatus status) {
    switch (status) {
    case STATUS_UNKNOWN:
        cout << "New status: Unknown" << endl;
        break;
    case STATUS_CONNECTED:
        cout << "New status: Connected" << endl;
        break;
    case STATUS_DISCONNECTED:
        cout << "New status: Disconnected" << endl;
        break;
    case STATUS_ERROR:
        cout << "New status: Error" << endl;
        break;
    }
    
    currentStatus = status;
}

void authCallback(map<string, string> resultMap) {
    if (resultMap.find("authenticationKey") != resultMap.end()) {
        string authenticationKey = resultMap.at("authenticationKey");
        if (authenticationKey.length() > 5) saveAuthenticationKey(authenticationKey); // do not save 'null'
    }
}

C++ Library

📘
What is an API function?

API Functions

Appendix A : Data Types

Appendix B: Windows Implementation.

📘
In this section you will find a setup guide for implementing the POS Buddy on a Windows based POS machine.

📘
In this section you will find a setup guide for implementing the POS Buddy on a Linux based POS machine.

📘What is an API function?

API Functions

Appendix A : Data Types

Appendix B: Windows Implementation.

📘In this section you will find a setup guide for implementing the POS Buddy on a Windows based POS machine.

📘In this section you will find a setup guide for implementing the POS Buddy on a Linux based POS machine.

📘
What is an API function?

📘
In this section you will find a setup guide for implementing the POS Buddy on a Windows based POS machine.

📘
In this section you will find a setup guide for implementing the POS Buddy on a Linux based POS machine.