Checking the License Data of the Supplied License Key
The checkLicenseKey:returningLicenseArray: function checks the Server for the license data for the supplied licenseKey. Whereas checkLicenseKey:returningLicenseArray: is a passive check, setLicenseKey:returningLicenseArray:sessionID: 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 checkLicenseKey:returningLicenseArray: function can be called between startSDK and stopSDK:, and can be called zero or more times.
The checkLicenseKey:returningLicenseArray: function is a synchronous function returning when all functionality is completed.
checkLicenseKey:returningLicenseArray:
RUIRESULT ruiCheckLicenseKey(RUIINSTANCE* ruiInstance, const char* licenseKey, int32_t** licenseArray)
Parameters
The checkLicenseKey:returningLicenseArray: function has the following parameters.
|
Parameter |
Description |
|||||||||
|
key (NSString*) |
The license key to be tested. This function accepts an NSString* parameter that is the license key itself and an NSMutableArray 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 (NSMutableArray*) |
This is an out parameter. The Usage Intelligence SDK will always update the array object. This object should be released when the Usage Intelligence SDK Client no longer needs it. The value will be a 5-element integer array containing the License Status Flag values at the following indexes: 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) Note:Any of the array elements can be set to -1 to indicate the data is not available. The array elements (RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED, RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE, RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED, RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED) will be set to one of the following values:
The array element (RUI_LICENSE_ARRAY_INDEX_KEY_TYPE) will be set to one of the following License Type values: RUI_KEY_TYPE_UNCHANGED (-1) - Key Type is Unchanged (when in parameter) or Unknown (when out parameter) 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) |
Returns
The checkLicenseKey:returningLicenseArray: function returns one of the return status constants below.
|
Return |
Description |
|
RUI_OK |
Function successful. |
|
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. stopSDK: and Objective-C instance release 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_NULL |
Some API parameter is expected to be non-NULL, and is not. |
|
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
Passing “Test Key” as the key and checking the return.
//OS X / ObjC Example.
//Test a license key
RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.
NSString* prod_key = @"Test Key";
NSMutableArray* license_result = [[NSMutableArray alloc] init];
if ([mySDK checkLicenseKey:prod_key returningLicenseArray:license_result] == RUI_OK) {
//Check license key type
if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_TYPE] int32Value] == RUI_FUNCTION_NOT_AVAIL) {
NSLog(@"License key information is unavailable");
} else {
NSLog(@"License key type is %d", [license_result[RUI_LICENSE_ARRAY_INDEX_KEY_TYPE] int32Value]);
}
//Check if the license is activated
if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE] int32Value] == RUI_KEY_STATUS_YES) {
NSLog(@"License is active");
} else if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_ACTIVE] int32Value] == RUI_KEY_STATUS_NO) {
NSLog(@"License is NOT active");
} else {
NSLog(@"License active status unknown");
}
//Check if key is blacklisted
if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED] int32Value] == RUI_KEY_STATUS_YES) {
NSLog(@"Key is blacklisted");
} else if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_BLACKLISTED] int32Value] == RUI_KEY_STATUS_NO) {
NSLog(@"Key is NOT blacklisted");
} else {
NSLog(@"Key blacklisted status unknown");
}
//Check if key is expired
if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED] int32Value] == RUI_KEY_STATUS_YES) {
NSLog(@"Key is expired");
} else if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_EXPIRED] int32Value] == RUI_KEY_STATUS_NO) {
NSLog(@"Key is NOT expired");
} else {
NSLog(@"Key expiration status unknown");
}
//Check if key is whitelisted
if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED] int32Value] == RUI_KEY_STATUS_YES) {
NSLog(@"Key is whitelisted");
} else if ([license_result[RUI_LICENSE_ARRAY_INDEX_KEY_WHITELISTED] int32Value] == RUI_KEY_STATUS_NO) {
NSLog(@"Key is NOT whitelisted");
} else {
NSLog(@"Key whitelisted status unknown");
}
} else {
NSLog(@"Failed to invoke function checkKey");
}
// [prod_key release]; //Either release or use ARC.
// [license_result release]; //Either release or use ARC.