Developers SDK

VPN Unlimited SDK v2.0 for Windows

Getting started

Overview

VPN Unlimited SDK for Windows is shipped as a dynamic link library. It is written in C++ and is available for Windows Vista and later. Supports MSVC 2019 compilers. You may download both 32 bit and 64 bit versions of the library.

Setup

Drag and drop the 'lib' folder into your project directory.

In order to use the SDK, you have to link the following libraries to your project:

  • vpnu_sdk.dll
  • cares.dll
  • libcurl.dll
  • libcrypto-1_1.dll
  • libssl-1_1.dll

Then, include header files from the 'include' folder into your project.

After that, copy the 'openvpn' and 'wireguard' folders somewhere into the project output directory. You'll need it to connect to VPN servers and configure the Windows network. Below you can find more detailed infromation.

After setup is done, you will be able to use all the classes from the SDK by including header files from the 'include' folder.

Note:

The сurrent version of the VPN Unlimited SDK uses the following libraries under the hood:

  • libcurl
  • libopenssl
  • libcares
  • libcrypto
  • libjansson

If your project uses one of these libraries and you get conflicts, please contact the VPN Unlimited support team for further investigation.

Classes

This SDK is designed in the classical OOP style. We don't provide one single interface, but rather a variety of interfaces which you can use in any desired combination. All API network calls are asynchronous, but are processed in a single thread query. All classes and structures belong to the VPNU namespace.

You can view the complete documentation for each class at the Reference page.

Here we just briefly describe the standard workflow.

SDK Initialization

There are three main SDK parts: API Talker, VPN Manager, VPN Service.

In order to use the SDK, it is necessary to set a unique service name (you can recieve it from the VPN Unlimited team) and override some interfaces. You can find complete information below.

The ApiTalker class allow you to send requests to VPN Unlimited API servers. To send a specific request you just need to call one of the ApiTalker methods. To retrieve the result, you need to override the IAPIDelegate interface and declare response handlers. Each handler has a unique operation id (the same as the one returned by the ApiTalker method), a response status, and related info such as parameters.

The IAppInfoProvider interface must be overridden and used as a parameter of the ApiTalker constructor. There are 4 methods you need to override:

  • IAppInfoProvider::getApplicationName() must return your application unique name.
  • IAppInfoProvider::getApplicationVersion() is preferred to return the app version in the "X.Y" format, where "X" is major and "Y" is minor version of the application.
  • IAppInfoProvider::saveValue(const std::string& key, const std::string& value) method is for some temporary data storing inside a user's system. This method may be empty, but we strongly recommended to implement it in order to minimize API calls response time in countries with restrictions.
  • IAppInfoProvider::getValue(const std::string& key) method is the same as previous, but for retrieving temporary data.

The VPNManager class is a singleton class, which provides any VPN related logic. To initialize this class you need to define VPNSettings, which set the path to the 'openvpn.exe' file (part of the SDK package), the path to the temporary folder (where logs and configs will be placed), the unique service name (the same as for ApiTalker), and the unique IKEv2 protocol connection name. Also you need to override the IVPNDelegate interface to handle VPN connection statuses and errors.

The VPNService class is a singleton class, which helps you to maintain the VPN Connection outside the app. It is needed when you don't want your application to request admin rights. The best way to implement this is to create the Windows service that starts automatically and doesn't require to request admin rights everytime.

SDK Initialization Example

IAppInfoProvider override example: 

class AppInfoProvider : public VPNU::IAppInfoProvider
{
    virtual std::string getApplicationName()
    {
        return "BestVPNApplicationEver";
    }

    virtual std::string getApplicationVersion()
    {
        return "1.0";
    }

    virtual void saveValue(const std::string& key, const std::string& value)
    {
        // save somewhere inside a user's system, in the registry, for example
    }

    virtual std::string getValue(const std::string& key) const
    {
        // read from the registry, for example
    }
};

IAPIDelegate override example: 

class APIDelegate : public VPNU::IAPIDelegate
{
    virtual void onAccountStatus(uint64_t operation_id, const VPNU::AccountStatus& status, VPNU::tVPNError error)
    {
        checkOperationId(operation_id); // You may implement the method to check if the response with such id is valid and not expired. Not necessary.
        if(error != VPNU::SUCCESS)
        {
            // something is wrong
        }
        else
        {
            // process status
        }
    }

    ...
};

IVPNDelegate override example: 

class VPNDelegate : public VPNU::IVPNDelegate
{
    virtual void stateChanged(const VPNU::VPNState& state)
    {
        // update the VPN connection status in the application UI
    }

    virtual void errorOccurred(const VPNManagerError& error)
    {
        // show an error notification
    }

    ...
};

Initialization: 

AppInfoProvider* infoProvider = new AppInfoProvider();
APIDelegate* apiDelegate = new APIDelegate();
VPNU::APITalker* talker = new VPNU::APITalker("bestvpnserviceever.42", infoProvider, vpnDelegate);

VPNDelegate* vpnDelegate = new VPNDelegate();
VPNU::VPNSettings settings("bestvpnserviceever.42", "C://bestvpn-temp/", "openvpn.exe", "BESTVPN IKEv2 Connection", "WireImpl.exe");
VPNU::VPNManager::getInstance().init(vpnDelegate, settings)

Note:

If you want to use OpenVPN or Wise protocols, then TAP-Windows is required to be installed on a user's system. Otherwise you will not be able to connect this user to any VPN server via OpenVPN or Wise. You may find it inside the SDK package. It's only be possible to connect via IKEv2 protocol.

FAQ

In every example in the FAQ section it is implicitly considered that the SDK is set up properly before any calls.

Other versions: 1.0