PLUSNative Sample Applications

The PLUSNative samples show you how you can integrate the PLUSNative API with your applications. These samples include support for a variety of popular languages and GUI frameworks, including (but not limited to) C++ with MFC, C++ with wxWidgets, Delphi, Objective C, and Visual Basic 6.

Include Files

The Protection PLUS 5 SDK installation directory has a sub-directory named Include. Each file in this directory contains definitions your application needs to call PLUSNative, and in many cases, it may also contain helper functions that simplify the use of PLUSNative by addressing language-specific limitations and nuances. (An example if this is how the Visual Basic 6 PLUSNative.bas file has its own implementation for SK_ApiResultCodeToString, so you do not need to worry about how to properly deal with string buffers allocated by our library in your code.)

Library Files

The Protection PLUS 5 SDK installation directory also contains a sub-directory named Library. Here, you will find a variety of builds of the PLUSNative API, which are organized as outlined below.

Dynamic Link Libraries / Shared Objects

Dynamic Link Libraries (DLLs), or shared objects, are organized with the following structure: Operating System/[DLL/shared]/Architecture. So for example, the 64 bit Windows DLL is located in Library\Windows\DLL\x64, and the universal OS X library is located in Library/macOS/shared/universal. When used, you will need to distribute one or more library files with your protected application(s).

Static Libraries

Static libraries allow you use PLUSNative with your application(s) without the need to distribute additional library files (this only applies to languages that can statically link a C library, such as C/C++). These files are organized with the following structure: Operating System/Development Environment/[import/static/static-nodeps]/Architecture. The third-level of this structure describes the nature of the static libraries, which include:

Next, you might also notice the static libraries for Windows include two versions named PLUSNative.lib and PLUSNative_md.lib. This is related to the Runtime Library setting in Visual C++ projects (under Configuration Properties/C++/Code Generation in the project properties). The PLUSNative.lib file may be used with the "Multi-threaded (/MT)" and "Multi-threaded Debug (/MTd)" runtime libraries, while the PLUSNative_md.lib file may be used with the "Multi-threaded DLL (/MD)" and "Multi-threaded Debug DLL (/MDd)" runtime libraries.

Sample Source Files

On Windows, the %PUBLIC%\Documents\SoftwareKey\Protection PLUS 5\Samples directory can be opened by running Protection PLUS 5 SDK from your start menu/screen, and clicking on the Protection PLUS 5 SDK Samples link. On other operating systems, you will choose where to extract the development files during installation, which will include the samples.

The sample directory contains sub-directories organized in the following manner: Operating System/Development Environment/Language/GUI Framework/Sample Project Directory.  So for example, the MFC samples can be found under the Windows\Visual Studio\C++\MFC sub-directory, and Objective C samples may be found under the macOS/Xcode/Objective-C/Cocoa subdirectory.

Important

Many of the source code comments begin with TODO and IMPORTANT. It is very important that you review each of these comments in any and all files you copy into your application. Each of these comments indicates an area where you need to make an informed decision about how the application should behave and react in certain scenarios.  Disregarding these comments can lead to undesirable behaviors in your application.

The "LicensingSample" Sample Projects

Any "LicensingSample" project, regardless of the language and GUI framework used in the individual sample, supports the same set of licensing features out-of-the-box. This includes features such as online activation, manual activation, copy-protection, and more. Additionally, these samples support different types of licenses, including time-limited evaluation/trial licenses, perpetual (non-expiring) licenses, and activated time-limited (or lease/periodic) licenses. The sample is also smart enough to automatically use a read-only license file issued by SOLO Server when appropriate (such as for perpetual licenses), or use writable license files when appropriate (such as for time-limited licenses, including evaluation licenses).

The names and contents of the files included with the LicensingSample projects do vary based on language and GUI framework; however, each version of this sample project does have the same general set of items:

Of course, some versions of the project could include additional source files, such as customized controls (like text boxes that limit user input).

LicensingSample Features

The LicensingSample projects all contain the same general features and functionality, regardless of the target language or platform. The most relevant of the features are summarized below.

Making the LicensingSample Work Exclusively with Read-Only Licenses

The LicensingSample demonstrates using read-only licenses and falling back to writable licenses. For those using only read-only licenses there are a few code changes that must be made to the sample code. The License class contains a Reload method which contains the few lines of code needed to be removed and modified in order to have the LicenseSample only use read-only licenses. Normally, in this method, if the read-only license is not found the code falls back to open a writable license and if that is unsuccessful it will create a writable license. The new method should remove the fallback code and look like the following code snippet.

C/C++
void License::Reload()
{
SK_ResultCode result = SK_ERROR_NONE;
m_IsLoaded = false;
SetWritable(false);
// Try to load the license file as read-only
if (SK_ERROR_NONE != (result = SK_PLUS_LicenseFileLoad(m_Context, SK_FLAGS_NONE, ToUTF8(m_LicenseFilePath).c_str())))
{
m_LastErrorNo = result;
}
else
{
m_IsLoaded = true;
}
// Notify our application to update it's status
if (m_RefreshLicenseStatusCallback)
m_RefreshLicenseStatusCallback();
}

In addition to the above changes, you will need to make changes in the RefreshLicenseStatus method callback of the MainDlg by removing the evaluation check code from the method. As there may not be a license file loaded, you will need to move the code to read and append the registration data into the if (licenseValid) code block.

The "CloudContolledNetworkFloatingSOLOServer" Sample Projects

These projects show how you can leverage PLUSNative and SOLO Server to provide Cloud-Controlled Network Floating Licensing using SOLO Server. For more information, you can read more about:

The sample applications may be used with the SOLO Server test author account. If you wish to use Cloud-Controlled Network Floating Licensing with your SOLO Server account, you will need to contact us for additional details on how to do so.

Configuring the Qt Samples

The Qt samples are configured to build on Windows, macOS, and Linux platforms. The Qt LicensingSample has been tested using Qt Open Source with version 5.7 components.

Configuring Qt for Windows Samples

Visual Studio 2013, 2015, or 2017 users can use the "Qt Visual Studio Tools" extension. To install the extension, open Visual Studio and select Tools/Extensions and Updates from the menu. Search the Online section for "Qt" and download/install the "Qt Visual Studios Tools" extension. Restart Visual Studio and an additional "QT VS TOOLS" menu is available. In the QT VS TOOLS menu, select Qt Options and set the path to your installed Qt components. In the QT VS TOOLS menu select Open Qt Project File and browse to the sample folder which contains the sample's *.pro file. Open this project file and the Visual Studio project file will be created. You may then build and run the project in Visual Studio.

The sample's Qt project file contains the information to link the Protection PLUS 5 SDK libraries. If you are using the static Protection PLUS 5 SDK libraries and building with a version of Visual Studio previous to Visual Studio 2015, you will need to modify the Qt project file to change the library paths. The instructions for doing so are within the sample Qt project file.

Configuring Qt for macOS and Linux Samples

Open the sample's *.pro file in Qt Creator, select a release or debug build, and build the sample. The project file is configured to link the Protection PLUS 5 SDK 64-bit static libraries and may be modified to use other Protection PLUS 5 SDK libraries. If you uncompressed or moved the samples, you will need to update the relative paths to the Include folder and the library in the Qt sample project file. The relative Include and Library paths in the project file are configured with Shadow Build off when building on Linux. If Shadow Build is turned on, the Include folder and library folder paths will need to be modified in the project file.

Configuring your system to use the wxWidgets samples

Although PLUSNative includes samples that use wxWidgets, it is not a dependency or requirement for using PLUSNative. However, it is one of many GUI libraries that is convenient to use because of its support for multiple operating systems. The PLUSNative samples require wxWidgets 2.8 or later. If you are downloading wxWidgets manually, then we generally recommend using the latest version to maximize compatibility with the latest versions of operating systems. Also, be careful to download the version with the DOS line endings when building for Windows, and download the version with Unix line endings when building for other operating systems.

The directions below are designed to help you get started with the wxWidgets samples that ship with PLUSNative, but they do not provide additional instruction for making multiple builds of wxWidgets for different processor architectures (x86, x64) or different underlying GUI libraries.  This means that, if your application needs to support multiple processor architectures, and/or multiple GUI libraries, you are responsible for establishing the additional steps and project/build configurations as necessary.

Download wxWidgets using NuGet on Windows

If you use Microsoft Visual Studio to build your Windows applications (or if you are just using it to review our sample applications), the easiest way to get started with the wxWidgets samples is to use the wxWidgets NuGet package. Simply follow the instructions at https://wiki.wxwidgets.org/Microsoft_Visual_C++_NuGet to download the templates and configure the project.

Manually building wxWidgets on Windows

Step 1: Determine the version of the Visual C++ compiler you will be using

If you only have one version of Visual Studio installed, then you will be using that version to compile your C++ applications. However, it is also possible to use a newer version of the Visual Studio IDE while using an older version of the platform toolset to use an older version of the C Runtime (CRT). (This is often done to support older versions of Windows, while still leveraging newer IDE features.) To determine the version of the Visual C++ compiler your project uses, open the project and click the Project/Properties menu, and observe the value selected under the "Platform Toolset" property on the Configuration Properties/General page. The value listed here will also tell you the version number (e.g. "Visual Studio 2008 (v90)"), which you will need in a later step.

Step 2: Determine which CRT is being used

The C Runtime (CRT) can be linked dynamically or statically, and it is important that you compile wxWidgets to link the CRT the same way your application does.  (Most applications will link the CRT dynamically.) You can view this setting by opening your project, click the Project/Properties menu, expanding the C/C++ section, selecting the "Code Generation" page, and observing the value in the "Runtime Library" property. If this property is set to "Multithreaded DLL (/MD)" or "Multithreaded Debug DLL (/MDd)", then your program links the CRT dynamically.  Otherwise, if this is set to "Multithreaded (/MT)" or "Multithreaded Debug (/MTd)", then your program links the CRT statically. You will need to take note of this for a later step.

Step 3: Determine the target architecture

If you open your project, click the Project/Properties menu, you will see a "Platform" option that shows what architecture you are targeting.  If it shows Win32, then your application should be targeting 32-bit (x86) processor architecture. If it shows x64, then it is targeting 64 bit (x64, also known as amd64) processor architecture. If you expand the Linker section, click Advanced, and observe the "Target Machine" property, you can also confirm the target architecture here.

Step 4: Build wxWidgets

Now that you have gathered all the required information, you can finally build wxWidgets using a command similar to the one below:

Windows Command Prompt
"%VS110COMNTOOLS%..\..\VC\bin\amd64\vcvars.bat"
nmake /f makefile.vc BUILD=release DEBUG_INFO=0 RUNTIME_LIBS=static TARGET_CPU=X64

You may need to alter the highlighted parts of the commands shown above as follows:

  1. %VS110COMNTOOLS% is an environment variable that points to the Visual Studio 2012 directory. If you determined your application targets a C Runtime library for a different version of Visual C++, then you will need to update this to use the appropriate environment variable for that version. Additionally, the name of "vcvars.bat" may vary depending on the architecture being targeted and the version of Visual Studio being used. You may need to browse to the directory where this batch file is located to determine the name of the file.
  2. If you determined that your application is linking the C Runtime library dynamically in step 2, then remove RUNTIME_LIBS=static from the command.
  3. If you determined that your application is targeting 32 bit (x86) architecture, then remove amd64\ from the first line, and remove TARGET_CPU=X64 from the second line.

Step 5: Set your environment variable

Most wxWidgets applications, and consequently the PLUSNative sample applications, use a WXWIN environment variable to determine where the wxWidgets header files and libraries may be found. You will need to add this environment variable, and set its value to the directory where you have just built wxWidgets. Once this is done, the PLUSNative samples should compile and link. If you run into difficulty getting them to do so, you may contact us to get help.

Manually building wxWidgets on macOS

If you already use a third-party package management system (such as Fink, Homebrew, or MacPorts) on your development system, it is possible to leverage this to install wxWidgets. However, this might not suffice for your needs if you need to statically link wxWidgets, or distribute the libraries with your application. Furthermore, it is also important that you use the latest version of wxWidgets, as version 2.8 does not support 64 bit Cocoa applications.

To build wxWidgets, open a terminal, change directory to where you download and extracted wxWidgets, and run the commands shown below. The --disable-shared option makes it compile static libraries, and you can remove this if you prefer to compile shared objects.

Terminal
./configure --with-osx_cocoa --disable-shared
make
sudo make install
sudo ln -s /usr/local/bin/wx-config /usr/bin/wx-config

The last command creates a symbolic link to the wx-config script in your /usr/bin directory, as this is often the easiest way to allow the compiler to find this script. Our wxWidgets samples rely on this script to configure compiler and linker flags needed to use wxWidgets.

Also note that you may need to consider the minimum version of OS X you plan to target with your application. For example, our wxWidgets samples use the -mmacosx-version-min=10.5 flag to tell the compiler to make sure the sample application is compatible with OS X 10.5 and later. You may need to specify matchign flags when compiling wxWidgets to avoid linker errors.

Manually building wxWidgets on Linux

Linux distributions generally include a package management system which you can use to install wxWidgets and its development files.  However, this might not suffice for your needs if you need to statically link wxWidgets, or distribute the libraries with your application. Additionally, you may need to use the latest version of wxWidgets, as version 2.8 does not support GTK+ 3.

Step 1: Install dependencies

Before you get started, you will need to determine what dependencies you will have, and ensure they are installed. For example, this often includes libgtk2.0-dev or libgtk-3-dev (for GTK+ 2 and GTK+ 3, respectively). Refer to the documentation for the Linux distribution you have installed for more information on how to install the required packages using its package management system.

Step 2: Build wxWidgets

To build wxWidgets, open a terminal, change directory to where you download and extracted wxWidgets, and run the commands shown below. Note that if your application uses GTK+ 2, you will need to change --with-gtk=3 to --with-gtk=2. Additionally, the --disable-shared option makes it compile static libraries, and you can remove this if you prefer to compile shared objects.

Terminal
./configure --with-gtk=3 --disable-shared
make
sudo make install

Also note that not all Linux distributions use sudo for privilege escalation.  If you are running such a distribution, you may need to run the su command before running the make install command.