PLUSNative Overview

If your application is a native application (written in C/C++, for example), or is written in a language which can make calls to shared/dynamic-link libraries, then PLUSNative is the API designed for your needs (see more about selecting a solution).

The purpose of this section is to guide developers through the process of using the PLUSNative API in applications. Understanding this portion of the manual and using the API effectively requires at least a basic understanding of application development and procedural programming, and also requires a basic understanding of the SoftwareKey System^tm and licensing.

Important

The steps laid out in the common implementation sub-topics of this manual do not match exactly what is in the Protection PLUS 5 SDK sample projects. The manual topics are more simplified to make it easier to explain, while the sample projects have more complex organization, but the resulting functionality is similar in both cases.

Calling Conventions

Calling conventions define how functions or subroutines receive parameter data from the calling code, as well as how the a result is returned. The default calling convention used by your application can vary on operating system, processor architecture, and the programming language used. If you are using an include file provided with PLUSNative (such as PLUSNative.h for C/C++, PLUSNative.bas for Visual Basic 6, PLUSNative.pas for Delphi), then the calling conventions will already be specified correctly for your application. However, if you find you need to define the function prototypes for calling PLUSNative functions, then using the correct calling convention is imperative. The calling conventions used are as follows:

32 bit (x86) versions of Windows use stdcall.
32 bit (x86) versions of Linux and OS X use cdecl.
64 bit (x86_64) versions of Windows, Linux, and OS X use fastcall.

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:

import: These are import libraries that may be linked when using Dynamic Link Libraries (DLLs)/Shared Objects.
static: These are static libraries which include third-party dependencies used by PLUSNative, such as OpenSSL, libcurl, and libxml2.
static-nodeps: These are static libraries which do not include third-party dependencies used by PLUSNative. There are some cases (unrelated to the use of PLUSNative) where you might need to link your own dependencies, such as if you need to use a different version, or if you use a custom patch to resolve some issue your application experienced with the dependency. For these niche scenarios, the libraries in static-nodeps may be used, but leave you responsible for linking all of the required dependencies (OpenSSL, libcurl, and libxml2).

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.

Getting Acquainted with the PLUSNative API

There are a few things you need to know when implementing PLUSNative.

Understanding PLUSNative's I/O functions

PLUSNative has a variety of functions available to assist with common file input and output (I/O) tasks that are generally necessary for licensing, but are made available to you for convenience. The relevance of these convenience functions to PLUSNative is that they provide you a way to fully control all steps of reading and saving licensing data, while also helping you avoid potential conflict with PLUSNative in areas like character encoding, memory management, formatting requirements, etc... PLUSNative offers a few different types/levels of convenience functions to consider for reading and saving license data:

High-level functions with built-in I/O includes functions such as SK_PLUS_LicenseFileLoad, SK_PLUS_LicenseFileSave, SK_PLUS_LicenseAliasAdd. These functions accept a path to files or registry keys (in Windows), and automatically determine what type of path was provided. These functions will also automatically change permissions (unless you opt-out by specifying the global SK_FLAGS_PERMISSIONS_NEVER_AUTO_SET flag in the context).
High-level functions without built-in I/O includes functions such as SK_PLUS_LicenseLoad, SK_PLUS_LicenseGetXmlDocument, SK_PLUS_LicenseGetDocumentString. When combined with the XML Encryption functions provided by PLUSNative, these can be leveraged to work with licenses that are loaded and saved using your own I/O routines. This gives you full control over where and how license data is stored, thus allowing you to store license data in custom locations (such as in a database, a custom hardware location, etc...).
XML Encryption functions includes functions like SK_XmlDocumentEncryptRsa and SK_XmlDocumentDecryptRsa, which can be used for accessing data outside of higher-level functions, implementing custom I/O, and implementing customized web service requests.
Low-level access functions includes functions such as SK_FileReadAllText, SK_FileWriteAllText, SK_RegistryValueGet, SK_RegistryValueSet. These functions only accept the type of path as indicated in the function name (e.g. SK_FileReadAllText does not accept a registry path), they do not perform any other special tasks automatically (such as setting permissions). However, they provide a simple way of retrieving string data from a file or registry key that may be used in further calls to PLUSNative functions. For example, this could include things like loading manual activation data from an unfinished activation attempt, retrieving some information for use in a custom identifier, etc...

Working with Windows Registry Paths

When working in Microsoft Windows, you may opt to store the license file and/or alias files in the registry. To use registry paths in PLUSNative that support them, you will need to specify either the hive or a special prefix to the path string to indicate the hive you wish to access as follows:

Hive	Prefix
HKEY_CURRENT_USER	:CU:
HKEY_LOCAL_MACHINE	:LM:
HKEY_CLASSES_ROOT	:CR:

Additionally, the name of the value must be appended to the end of the path, after a colon (:) character. So for example, to access a value named MyValue under a HKEY_LOCAL_MACHINE\Software\MyCompany\MyProgram key, you would provide PLUSNative a path like: ":LM:Software\MyCompany\MyProgram:MyValue" or "HKEY_LOCAL_MACHINE\Software\MyCompany\MyProgram:MyValue".

The following API functions support registry access on Windows:

SK_PLUS_LicenseFileLoad

SK_PLUS_LicenseFileSave

SK_PLUS_LicenseAliasAdd

SK_XmlDocumentLoadFile

Strings, Encoding, and Locale

As a C API, PLUSNative uses null-terminated strings. By default, PLUSNative relies on a neutral locale, and expects all strings to use UTF-8 encoding. Additionally, PLUSNative dynamically allocates strings so they only use the amount of space that is required. The benefit is that there is no need to worry about allocating a buffer with enough space, reallocating buffers when there is not enough space, and it tends to be much easier to work with when using higher-level programming languages and frameworks. However, the downside is that you are responsible for freeing the memory allocated using the provided SK_StringDispose function. In most cases, sample code or language bindings provided will handle this for you reliably. However, this is definitely something to be well aware of when implementing PLUSNative using a language where bindings have not already been provided. See the memory management section below for additional details.

Memory Management

Since PLUSNative provides a C API, it is necessary for memory to be managed correctly. In general, safest approach is to base your code off our sample applications. This is because the sample code (which is generally written in higher-level languages, like C++, Objective C, etc...) already manages memory for you correctly. However, if you are implementing PLUSNative from scratch, then it's pivotal that you understand how to manage memory correctly with this API. Failing to do so can result in memory leaks, random crashes, and can leave your users with a general experience of instability with your application(s). The important things you must understand to avoid these kinds of issues are outlined at a high level below.

Initialization Functions

In PLUSNative, initialization functions can include any function that allocates memory for an object which is returned. This can include things such as the API Context, a string, an XML document, etc...

Disposal Functions

When your application is done using some object or data that PLUSNative has provided/returned, you must use PLUSNative to de-allocate the memory that was previously allocated from an initialization function.

Understand Best Practices

Proper memory management is a critical area of concern for programmers, as it can affect application performance, stability, and (perhaps most importantly) security. Preventing leaks and memory corruption is essential to providing your users a responsive, reliable, and safe experience with your applications. Some practices are outlined below that can be helpful in general, and are essential when using PLUSNative.

Initialize Variable Values

Any time you declare a variable, especially a pointer or an array, initialize the data. (Generally, this data should be initially zero.) Some examples include:

Initialize buffer/array elements to 0 -- especially character arrays. For example: char mychar[10] = {0}; will initialize all array elements to 0, making mychar an empty string intially. (If you allocate memory on the heap, C/C++ applications can use the ZeroMemory macro [Windows only] or the memset function to zero the memory after the declaration.) Doing this helps ensure that anything that might be called on this string (such as strlen) before the value is initialized with a meaningful string will not run over the bounds of the buffer allocated.
Initialize numeric values to 0 or the most appropriate value for the variable's use. This is especially important for anything used for Boolean expressions, where 0 valuates to false, and any other value evaluates to true. This can help ensure that, should the value not be initialized due to some unexpected condition, your application behaves in the safest way possible.
Always initialize pointers to NULL (or 0) at declaration. This prevents you from accidentally attempting to free memory that was never really allocated later in code (should you attempt to free memory with an uninitialized pointer). All PLUSNative initialization functions require your pointer to be initialized this way, so as to reject uninitialized pointers that may point to invalid memory addresses, or pointers that point to addresses which must first be freed before creating a new allocation (which would otherwise cause memory leaks).

Verify Pointers

First, consistently initializing pointers to NULL (as described above) is a critical part of verifying pointers reliably. With that practice firmly in place, you can always check that a pointer is not NULL before attempting to use it. Consider the following example excerpt of bad code:

C/C++: char *myString = NULL;
size_t myStringSize = 10;
myString = (char *)malloc(myStringSize);
memset(myString, 0, myStringSize); /*It is bad to do this without checking the pointer first!*/
/*The program might have additional statements here, which could use myString.*/
free(myString); /*It is bad to do this without checking the pointer first!*/

Should the malloc function fail in the example above, the program would crash with an access violation in memset because myString would contain a NULL value. And because it is relatively unlikely for you to run into this condition while debugging and testing yourself, it is more likely that a customer would eventually report the crash (either on a very old computer, or possibly one affected by malware). This can easily be avoided by consistently using basic control structures as shown in the next example excerpt:

C/C++: char *myString = NULL;
size_t myStringSize = 10;
do
{
myString = (char *)malloc(myStringSize);
if (NULL == myString)
{
/*Your application can handle error reporting here.*/
break;
}
memset(myString, 0, myStringSize);
/*The program might have additional statements here, which could use myString.*/
} while (0);
if (NULL != myString)
{
free(myString);
myString = NULL;
}

Using the do/while control structure allows us to check pointers and conveniently skip any logic that would otherwise attempt to use an uninitialized pointer. Of course, you can use any control structure (such as try/catch) you feel is appropriate; what matters most is that you are consistent with your practices.) Additionally, in the expression that checks the pointer, the constant value is on the left side of the expression so as to avoid accidental assignment. (For example, if (myString = NULL) would assign a NULL value to myString and cause a memory leak with this example; and the expression would always evaluate to FALSE, causing the same exact problem as the first example.)

Free Memory Safely and Consistently

Freeing memory safely is directly related to the previous two points on consistently initializing pointers and verifying pointers before use. Attempting to free memory using an uninitialized pointer is just as problematic as attempting to use uninitialized pointers. Additionally, using control structures as shown above is critical to ensuring there are no memory leaks. Consider the example below, which expands on the prior examples:

C/C++: char *myString = NULL;
size_t myStringSize = 10;
char mySecondString = NULL;
size_t mySecondStringSize = 20;
do
{
myString = (char *)malloc(myStringSize);
if (NULL == myString)
{
/*Your application can handle error reporting here.*/
break;
}
memset(myString, 0, myStringSize);

mySecondString = (char *)malloc(mySecondStringSize);
if (NULL == mySecondString)
{
/*Your application can handle error reporting here.*/
break;
}
memset(mySecondString, 0, mySecondStringSize);

/*The program might have additional statements here, which could use myString and/or mySecondString.*/
} while (0);
if (NULL != myString)
{
free(myString);
myString = NULL;
}
if (NULL != mySecondString)
{

In the example above, the benefit of this overall approach in organizing code is that it can prevent memory leaks in unusual circumstances such as having a successful allocation for myString, but a failed allocation for mySecondString (because myString is still freed even when we break out of the do-while loop because mySecondString's allocation failed).

Consistency is Key

The examples above are meant to provide high-level suggestions. As with many things, there are many ways to be right. Regardless of the specific control structures and variations from the suggestions and examples here, it is pivotal that you adhere to your practices strictly, and consistently.

Using Protection PLUS 5 SDK Native Edition in multiple threads

When implementing the PLUSNative library with multiple threads, there are specific steps to properly initialize and shutdown the library. If these steps are not correctly implemented, it could result in unexpected behavior or possibly memory leaks in the application.

An SK_ApiContext must be created on the main thread by calling the SK_ApiContextInitialize function and include the SK_FLAGS_APICONTEXTINITIALIZE_MAINTHREAD flag.
It is recommended that each thread using the PLUSNative library creates its own SK_ApiContext to use only within the thread creating it. Do not share an SK_ApiContext across threads.
Before disposing the SK_ApiContext on the main thread, all other threads using the PLUSNative library must be shutdown. Disposing the SK_ApiContext on the main thread before all other threads that are using the PLUSNative library could cause memory leaks.
Finally, dispose the SK_ApiContext on the main thread by calling SK_ApiContextDispose with the SK_FLAGS_APICONTEXTDISPOSE_SHUTDOWN flag.