C-Interface

10min
The C interface of LicenseSpring's C++ SDK allows using SDK features in C applications. This tutorial will explain how to implement licensing in a C application using the LicenseSpring SDK.
In this article we will look at activating, checking, and deactivating licenses. This functionality can be implemented using the LSLicenseHandler struct. It is a wrapper of C++ LicenseHandler class and is similar in use. 
SDK Configuration
To initialize the SDK you will need to fill in your application name and version, product code and either
API and shared key, or
OAuth client_id and client_secret.
OAuth support was added in v7.35.0 of the SDK. See OAuth Authorization﻿  on how to set up OAuth.
See the C++ SDK Configuration and Usage﻿ on how to retreive credentials.
When you have the necessary values, create the LSConfiguration object.
C
const char* AppName = "My LicenseSpring Application";
const char* AppVersion = "1.0.0";
// use in case of standard authentication
const char* ApiKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
const char* SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
// use in case of OAuth authentication
std::string ClientId = "xxxxxx-xxxxx-yyy";
std::string ClientSecret = "ssssssssssssssssssssssssssssss";

const char* ProductCode = "XX";

LSExtendedOptions* options = CreateLSExtendedOptions();

LSConfiguration* configuration = CreateLSConfiguration( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
FreeLSExtendedOptions( options );

// or
// options->setCryptoProviderKey( options, "password for license encryption key generation" );
// LSConfiguration* configuration = CreateLSConfigurationOAuth( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
// FreeLSExtendedOptions( options );
const char* AppName = "My LicenseSpring Application";
const char* AppVersion = "1.0.0";
// use in case of standard authentication
const char* ApiKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
const char* SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
// use in case of OAuth authentication
std::string ClientId = "xxxxxx-xxxxx-yyy";
std::string ClientSecret = "ssssssssssssssssssssssssssssss";

const char* ProductCode = "XX";

LSExtendedOptions* options = CreateLSExtendedOptions();

LSConfiguration* configuration = CreateLSConfiguration( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
FreeLSExtendedOptions( options );

// or
// options->setCryptoProviderKey( options, "password for license encryption key generation" );
// LSConfiguration* configuration = CreateLSConfigurationOAuth( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
// FreeLSExtendedOptions( options );
﻿
You have to create a LSExtendedOptions object even if you don’t intend to change its values. It is necessary to copy the default values to the LSConfiguration. Then you can delete the options object.
Now you can create and initialize LSLicenseHandler using this configuration.
C
LSLicenseHandler* lh = CreateLSLicenseHandler( configuration );
LSLicenseHandler* lh = CreateLSLicenseHandler( configuration );
﻿
License Activation
To activate a license, you need its key or user email and password. For information about getting license keys see: Key-based license activation﻿﻿
For information about user based licenses see: Adding user to a license﻿﻿
Using these values, create a LSLicenseID and call activation method.
C
LSLicenseID licenseId = CreateLicenseIDfromKey( "XXXX-XXXX-XXXX-XXXX" ); 
lh->activateLicense( lh, licenseId );
LSLicenseID licenseId = CreateLicenseIDfromKey( "XXXX-XXXX-XXXX-XXXX" ); 
lh->activateLicense( lh, licenseId );
﻿
Local License
Make sure that you check if a license exists on the device before a new activation. For more information see: C++ SDK Configuration and Usage﻿ 
C
if( !lh->isLicenseExists( lh ) )
  //activate a new license
if( !lh->isLicenseExists( lh ) )
  //activate a new license
﻿
License Check
It is recommended to perform a local license check at application start to confirm that the local license file belongs to the current device, has not been tampered with and is still valid. 
Online license check refreshes the local license with the data from LicenseSpring backend.
C
lh->checkLicenseLocal( lh );//local check

LSInstallationFile* pInstallFile = lh->checkLicense( lh );//online check
        if( pInstallFile )
            FreeLSInstallationFile( pInstallFile );

lh->checkLicenseLocal( lh );//local check

LSInstallationFile* pInstallFile = lh->checkLicense( lh );//online check
        if( pInstallFile )
            FreeLSInstallationFile( pInstallFile );
﻿
This method also returns the most recent LSInstallationFile available for the license which can be useful for managing software updates. [TODO: insert link to the article about handling versions]
You can also check for active, valid, enabled, and expired licenses using isLicenseActive, isLicenseValid, isLicenseEnabled, and isLicenseExpired methods respectively. 
Full Code Sample
Below you can find a code sample that initializes the SDK, retrieves a local license or activates a new one, and performs the necessary checks.
C
const char* AppName = "My LicenseSpring Application";
const char* AppVersion = "1.0.0";
// use in case of standard authentication
const char* ApiKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
const char* SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
// use in case of OAuth authentication
std::string ClientId = "xxxxxx-xxxxx-yyy";
std::string ClientSecret = "ssssssssssssssssssssssssssssss";

const char* ProductCode = "XX";

LSExtendedOptions* options = CreateLSExtendedOptions();

LSConfiguration* configuration = CreateLSConfiguration( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
FreeLSExtendedOptions( options );

// or
// options->setCryptoProviderKey( options, "password for license encryption key generation" );
// LSConfiguration* configuration = CreateLSConfigurationOAuth( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
// FreeLSExtendedOptions( options );

LSLicenseHandler* lh = CreateLSLicenseHandler( configuration );

if( !lh->isLicenseExists( lh ) )
{
    LSLicenseID licenseId = CreateLicenseIDfromKey( "XXXX-XXXX-XXXX-XXXX" ); 
    lh->activateLicense( lh, licenseId );
    if( lh->wasError( lh ) )
   	{
        const char* error = lh->getLastErrorMsg( lh );
        enum LSErrorCode code = lh->getLastError( lh );
        printf( "Error occurred. Message: %s Code: %d\n\n", error, code );
   	}
}

lh->checkLicenseLocal( lh );
if( lh->wasError( lh ) )
{
    const char* error = lh->getLastErrorMsg( lh );
   	enum LSErrorCode code = lh->getLastError( lh );
   	printf( "Error occurred. Message: %s Code: %d\n\n", error, code );
}

LSInstallationFile* pInstallFile = lh->checkLicense( lh );
if( pInstallFile )
    FreeLSInstallationFile( pInstallFile );

if( lh->wasError( lh ) )
{
    const char* error = lh->getLastErrorMsg( lh );
   	enum LSErrorCode code = lh->getLastError( lh );
   	printf( "Error occurred. Message: %s Code: %d\n\n", error, code );
}
const char* AppName = "My LicenseSpring Application";
const char* AppVersion = "1.0.0";
// use in case of standard authentication
const char* ApiKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
const char* SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
// use in case of OAuth authentication
std::string ClientId = "xxxxxx-xxxxx-yyy";
std::string ClientSecret = "ssssssssssssssssssssssssssssss";

const char* ProductCode = "XX";

LSExtendedOptions* options = CreateLSExtendedOptions();

LSConfiguration* configuration = CreateLSConfiguration( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
FreeLSExtendedOptions( options );

// or
// options->setCryptoProviderKey( options, "password for license encryption key generation" );
// LSConfiguration* configuration = CreateLSConfigurationOAuth( ApiKey, SharedKey, ProductCode, AppName, AppVersion, options );
// FreeLSExtendedOptions( options );

LSLicenseHandler* lh = CreateLSLicenseHandler( configuration );

if( !lh->isLicenseExists( lh ) )
{
    LSLicenseID licenseId = CreateLicenseIDfromKey( "XXXX-XXXX-XXXX-XXXX" ); 
    lh->activateLicense( lh, licenseId );
    if( lh->wasError( lh ) )
   	{
        const char* error = lh->getLastErrorMsg( lh );
        enum LSErrorCode code = lh->getLastError( lh );
        printf( "Error occurred. Message: %s Code: %d\n\n", error, code );
   	}
}

lh->checkLicenseLocal( lh );
if( lh->wasError( lh ) )
{
    const char* error = lh->getLastErrorMsg( lh );
   	enum LSErrorCode code = lh->getLastError( lh );
   	printf( "Error occurred. Message: %s Code: %d\n\n", error, code );
}

LSInstallationFile* pInstallFile = lh->checkLicense( lh );
if( pInstallFile )
    FreeLSInstallationFile( pInstallFile );

if( lh->wasError( lh ) )
{
    const char* error = lh->getLastErrorMsg( lh );
   	enum LSErrorCode code = lh->getLastError( lh );
   	printf( "Error occurred. Message: %s Code: %d\n\n", error, code );
}
﻿
License Deactivation
Deactivating a license unbinds the device from the license, and decrements the number of total activations. Deactivating is done using the following method:
C
if( lh->deactivateLicense( lh ) )
    printf( "License deactivated successfully.\n" );
if( lh->deactivateLicense( lh ) )
    printf( "License deactivated successfully.\n" );
﻿
Common Errors
The license checks can produce the following errors:
Error
Definition
eLicenseDisabled 
eLicenseInactive
eLicenseExpired
License is in invalid state (disabled, epired or inactive)
eProductMismatchError 
License does not belong to configured product
eDeviceError 
License does not belong to current device
eDeviceBlacklisted
The device has been blacklisted
eClockTamperedError
Detected cheating with system clock
eNoInternetError 
eNetworkTimeoutError
eServerError
Connection-related errors: if there's no Internet or an internal server error occured
eUnauthorizedClient
eOAuthRequired
eOAuthTokenExpired
Invalid client credentials.
License requires OAuth authentication.
OAuth token is expired. This shouldn't happen as the SDK keeps track of its lifetime.
﻿
Error	Definition
eLicenseDisabled eLicenseInactive eLicenseExpired	License is in invalid state (disabled, epired or inactive)
eProductMismatchError	License does not belong to configured product
eDeviceError	License does not belong to current device
eDeviceBlacklisted	The device has been blacklisted
eClockTamperedError	Detected cheating with system clock
eNoInternetError eNetworkTimeoutError eServerError	Connection-related errors: if there's no Internet or an internal server error occured
eUnauthorizedClient eOAuthRequired eOAuthTokenExpired	Invalid client credentials. License requires OAuth authentication. OAuth token is expired. This shouldn't happen as the SDK keeps track of its lifetime.
C++
Android support (EXPERIMENTAL)