Setting the Current License to the Supplied License Key
The setLicenseKey:returningLicenseArray:sessionID: should be called when an end user is trying to enter a new license key into your application and you would like to confirm that the key is in fact valid (i.e. blacklisted or whitelisted), active, or expired.
The setLicenseKey:returningLicenseArray:sessionID: function checks the Server for the license data for the supplied licenseKey and sets the current license to licenseKey.
Whereas checkLicenseKey:returningLicenseArray: is a passive check, setLicenseKey:returningLicenseArray:sessionID: changes the license key. The Server always registers the licenseKey even if the Server knows nothing about the licenseKey.
When a new (unknown) licenseKey is registered, the Server sets the license data to keyType RUI_KEY_TYPE_UNKNOWN and the four status flags (blacklisted, whitelisted, expired, activated) to RUI_KEY_STATUS_NO. The license array has size, indexes and values as specified in RUISDKDefines.h.
Note:Different from the V4 of the Usage Intellligence SDK, a sessionID parameter can be supplied,
Note:The order of the license array data has changed from the Usage Intelligence SDK V4.
The setLicenseKey:returningLicenseArray:sessionID: function can be called between startSDK and stopSDK:, and can be called zero or more times.
The setLicenseKey:returningLicenseArray:sessionID: function is primarily a synchronous function, returning once the check with Server has completed. Some post- processing functionality is performed asynchronously, executed on separate thread(s).
setLicenseKey:returningLicenseArray:sessionID:
(RUIRESULTOBJC) setLicenseKey: (NSString*)licenseKey returningLicenseArray: (NSMutableArray*)licenseArray sessionID: (NSString*) sessionID
Parameters
The setLicenseKey:returningLicenseArray:sessionID: function has the following parameters.
|
Parameter |
Description |
|
licenseKey (NSString*) |
The license key to be checked. This value cannot be empty. |
|
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: RUI_KEY_STATUS_UNCHANGED (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter). RUI_KEY_STATUS_NO (0) - Key Status is No. RUI_KEY_STATUS_YES (1) - Key Status is Yes. 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 setLicenseKey:returningLicenseArray:sessionID: 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
Changing the key to “Test Key Number 2” and checking the return.
//OS X / ObjC Example.
//Register a new license key
RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.
NSString* new_key = @"Test Key Number 2";
NSMutableArray* license_result = [[NSMutableArray alloc] init];
NSString* session_id = @"";
licenseResult[RUI_LICENSE_ARRAY_INDEX_KEY_TYPE] = RUI_KEY_TYPE_EVALUATION;
if ([mySDK setLicenseKey:new_key returningLicenseArray:license_result sessionID:session_id] == 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.