API Reference

C++ Sample Client

We have set up a little c++ demo client for you to kick off development.

👉 Download c++ demo client

C++ client

The C++ Client demo uses the official Microsoft SignalR C++ client and the vcpkg packaging tool. Although available and functional, the Microsoft C++ library is still in the status 'unsupported' according to Microsoft documentation so please make sure you check the github repository of the C++ client for updates and issues.

Building and running the demo client app on Windows with Visual Studio

In order to build and run the c++ client on Windows you need:

  • An x64 windows pc (windows 10 was tested)
  • Microsoft Visual Studio 2019 (or another modern c++ compiler which supports c++17 like clang or mingw)
  • (if not using visual studio) CMake 3.14 or newer
  • git

Steps needed to build the demo client (these steps apply to windows 10 x64 + Microsoft Visual Studio 2019):

  1. Clone and setup vcpk somewhere on your drive (use a short path, like c:\vcpkg or c:\src\vcpk. In a command prompt window (or, better, the Visual Studio developer command prompt):
c:\>mkdir src
c:\>cd src
c:\src>git clone https://github.com/microsoft/vcpkg.git vcpkg
  1. Bootstrap vcpkg and install the microsoft signalr library, the static linking version (this process will take a while but you only need to do it once):
c:\src>.\vcpkg\bootstrap-vcpkg.bat
c:\src>.\vcpkg\vcpkg install microsoft-signalr[cpprestsdk]:x64-windows-static
  1. After the library and its dependencies have been built and installed, enable the vcpkg integration with Visual Studio:
c:\src>.\vcpkg\vcpkg integrate install

Take note of the message CMake projects should use: "-DCMAKE_TOOLCHAIN_FILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake" in case you want to use CMake to build your project.

  1. You can now open the provided DemoClient.sln file in Visual Studio 2019, select Release configuration, then go to menu Project->Properties select Debugging and enter the api server url and your developer key, then build and run the solution.

The demo client should run an connect to the server.

If you call the Web API with the same api key, you should see a notification in the terminal window.

You can also build and run the demo client with CMake instead of Visual Studio (but it will only work if you have visual studio c++ compiler installed, if you want to use another compiler you need to change the CMakeLists.txt file):

  1. In the start menu visual studio folder click and open a developer command prompt or "x64 native tools command prompt" (in order to have cmake available in path), then cd to the democlient folder and run cmake to create the build files:
c:\>cd \work\samples\DemoClient
c:\work\samples\DemoClient>mkdir build
c:\work\samples\DemoClient>cd build
c:\work\samples\DemoClient\build>cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/src/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static
  1. Then run cmake to build the executable:
c:\work\samples\DemoClient\build>cmake --build . --config Release

Then you can also run the client from the Release folder:

c:\work\samples\DemoClient\build>cd Release
c:\work\samples\DemoClient\build\Release>demo.exe https://api.pickup.bd.com yourapikey

You should see the same result as when running from Visual Studio:

Building and running the C++ client on Linux

In order to build and run the c++ client on Linux you need:

  • a modern x64 linux distribution (we used Ubuntu 18.04)
  • a newer gcc (7.0 or more)
  • git

In order to build and run the demo client, follow the steps below (this was tested on ubuntu 18.04):

  1. Install build requirements:
developer@devserver:~$ sudo apt-get update
developer@devserver:~$ sudo apt-get install build-essential ninja-build curl zip unzip tar pkg-config wget lsb-release software-properties-common -y
  1. Upgrade cmake: the one which comes with the system is 3.10 and we need at least 3.14 so we will install it from the kitware repository (and we also uninstall the existing ubunt version, if any)
developer@devserver:~$ sudo apt-get remove --purge -y cmake
developer@devserver:~$ sudo wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
developer@devserver:~$ sudo apt-add-repository "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main"
developer@devserver:~$ sudo apt update
developer@devserver:~$ sudo apt install kitware-archive-keyring
developer@devserver:~$ sudo rm /etc/apt/trusted.gpg.d/kitware.gpg
developer@devserver:~$ sudo apt update

If apt complains about missing public key (it does on a default ubuntu 18 installation), add the key:

developer@devserver:~$ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 6AF7F09730B3F0A4

Then you can install the kitware cmake package:

developer@devserver:~$ sudo apt update
developer@devserver:~$ sudo apt install -y cmake
developer@devserver:~$ cmake --version
cmake version 3.23.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).
  1. Make sure you have linux-headers-your_kernel_version package (needed for building openssl, on ubuntu 18.04 it was preinstalled but in a docker container it may not be):
developer@devserver:~$ sudo apt-get install -y linux-headers-`uname -r`
  1. Copy the folder with the demo (we used /home/developer/DemoClient) and install vcpkg
developer@devserver:~$ cd /home/developer/DemoClient/
developer@devserver:~/DemoClient$ git clone https://github.com/microsoft/vcpkg.git
  1. Bootstrap vcpkg and install the microsoft signalr library (this process will take a while but you only need to do it once):
developer@devserver:~/DemoClient$ ./vcpkg/bootstrap-vcpkg.sh
developer@devserver:~/DemoClient$ ./vcpkg/vcpkg install microsoft-signalr[cpprestsdk]:x64-linux
  1. After the packages have been installed, now you can build and run the demo client:
developer@devserver:~/DemoClient$ mkdir build
developer@devserver:~/DemoClient$ cd build
developer@devserver:~/DemoClient/build$ cmake .. -DCMAKE_TOOLCHAIN_FILE=`readlink -f "$PWD/../vcpkg/scripts/buildsystems/vcpkg.cmake"`
developer@devserver:~/DemoClient/build$ cmake --build . --config Release
developer@devserver:~/DemoClient/build$ ./demo https://api.pickup.bd.com yourapikey

If you call the Web API with the same api key, you should see a notification in the terminal window.

Building and running the C++ client with Docker

The DemoClient folder contains also a Dockerfile which can be used to build an image with the client app (we tested this on linux only). Steps to build and run the image:

  1. change directory to the folder with the Dockerfile and build the image
developer@devserver:~/DemoClient$ docker build -t pickupcloud/rtapi-demo .
  1. run the image
developer@devserver:~/DemoClient$ docker run --rm -it pickupcloud/rtapi-demo https://api.pickup.bd.com yourapikey