Checking the License Data of the Supplied License Key
The ruiCheckLicenseKey() function checks the Server for the license data for the supplied licenseKey. Whereas ruiCheckLicenseKey() is a passive check, ruiSetLicenseKey() changes the license key. The license array has size, indexes and values as specified in RUISDKDefines.h.
Note:The order of the license array data has changed from the Usage Intelligence (Trackerbird) SDK V4.
The ruiCheckLicenseKey() function can be called between ruiStartSDK() and ruiStopSDK(), and can be called zero or more times.
The ruiCheckLicenseKey() function is a synchronous function returning when all functionality is completed.
RUIRESULT ruiCheckLicenseKey(RUIINSTANCE* ruiInstance, const char* licenseKey, int32_t** licenseArray)
Parameters
The ruiCheckLicenseKey() function has the following parameters.
|
Parameter |
Description |
|||||||||
|
ruiInstance (RUIINSTANCE*) |
Pointer to the Usage Intelligence instance created via ruiCreateInstance(). |
|||||||||
|
licenseKey (const char*) |
The license key to be checked. This value cannot be empty. The function accepts a const char* parameter that is the license key itself and an int32_t pointer to an array of length 5 that it fills with the returned result. You may use the following constants to refer to the required value by its index: RUI_LICENSE_ARRAY_INDEX_KEY_TYPE (0) RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED (1) RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE (2) RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED (3) RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED (4) Each of the values 1 through 4 will be set to either 0 or 1 that refers to false or true respectively. The first value (RUI_LICENSE_ARRAY_INDEX_KEY_TYPE) will be set to a number between 0 and 7 (inclusive) that refers to the 8 possible license types listed below. The values may also be -1 that means “Unknown”. The following are the possible license types: RUI_KEY_TYPE_UNCHANGED (-1) RUI_KEY_TYPE_EVALUATION (0) RUI_KEY_TYPE_PURCHASED (1) RUI_KEY_TYPE_FREEWARE (2) RUI_KEY_TYPE_UNKNOWN (3) RUI_KEY_TYPE_NFR (4) - Key Type is Not For Resale RUI_KEY_TYPE_CUSTOM1 (5) RUI_KEY_TYPE_CUSTOM2 (6) RUI_KEY_TYPE_CUSTOM3 (7) The following are the possible key status values:
|
|||||||||
|
licenseArray (int32_t**) |
The array that will be filled to contain the license status flags. |
Returns
The ruiCheckLicenseKey() function returns one of the return status constants below.
|
Return |
Description |
|
RUI_OK |
Function successful. |
|
RUI_INVALID_SDK_OBJECT |
SDK Instance parameter is NULL or invalid. |
|
RUI_SDK_INTERNAL_ERROR_FATAL |
Irrecoverable internal fatal error. No further API calls should be made. |
|
RUI_SDK_ABORTED |
A required New Registration has failed, and hence the SDK is aborted. ruiStopSDK() and ruiDestroyInstance() are possible. |
|
RUI_SDK_SUSPENDED |
The Server has instructed a temporary back-off. |
|
RUI_SDK_PERMANENTLY_DISABLED |
The Server has instructed a permanent disable. |
|
RUI_SDK_OPTED_OUT |
Instance has been instructed by the application to opt-out. |
|
RUI_CONFIG_NOT_CREATED |
Configuration has not been successfully created. |
|
RUI_SDK_ALREADY_STOPPED |
SDK has already been successfully stopped. |
|
RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY |
Some API parameter is expected to be non-empty, and is not. |
|
RUI_TIME_THRESHOLD_NOT_REACHED |
The API call frequency threshold (set by the Server) has not been reached. |
|
RUI_NETWORK_CONNECTION_ERROR |
Not able to reach the Server. |
|
RUI_NETWORK_SERVER_ERROR |
Error while communicating with the Server. |
|
RUI_NETWORK_RESPONSE_INVALID |
Message format error while communicating with the Server. |
Code Example
//Test a license key
bool useDefaultReachOutHandler = false;
RUIINSTANCE* mySDK = ruiCreateInstance(useDefaultReachOutHandler); //...; //Creation and initialization shown in other snippets.
char* myProductKey = "xyz";
int32_t* licenseResult = NULL;
RUIRESULT rc = ruiCheckLicenseKey(mySDK, myProductKey, &licenseResult);
if(rc == RUI_OK)
{
if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_TYPE] == RUI_KEY_TYPE_UNCHANGED) {
cout << "License key information is unknown\n" << endl;
} else {
cout << "License key type is " << licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_TYPE] << endl;
}
//Check if the license key is activated
if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE] == RUI_KEY_STATUS_YES){
cout << "License Active" << endl;
} else if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE] == RUI_KEY_STATUS_NO) {
cout << "License Inactive" << endl;
} else {
cout << "License key information is unknown" << endl;
}
//check if license key is blacklisted
if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED] == RUI_KEY_STATUS_YES){
cout << "License is blacklisted" << endl;
} else if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED] == RUI_KEY_STATUS_NO) {
cout << "License is NOT blacklisted" << endl;
} else {
cout << "License blacklist status unknown" << endl;
}
//Check if license key is expired
if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED] == RUI_KEY_STATUS_YES){
cout << "License is expired" << endl;
} else if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED] == RUI_KEY_STATUS_NO) {
cout << "License is NOT expired" << endl;
} else {
cout << "License expiration status unknown" << endl;
}
//Check if license key is white listed
if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED] == RUI_KEY_STATUS_YES){
cout << "Key is white listed" << endl;
} else if (licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED] == RUI_KEY_STATUS_NO) {
cout << "Key is NOT white listed" << endl;
} else {
cout << "Key white list status unknown" << endl;
}
} else {
cout << "Failed to invoke function ruiCheckLicenseKey()" << endl;
}
ruiFree(licenseResult);