Setting the Current License to the Supplied License Key
The RUISDK.SetLicenseKey function checks the Server for the license data for the supplied licenseKey and sets the current license to licenseKey.
Whereas RUISDK.CheckLicenseKey is a passive check, RUISDK.CheckLicenseKey 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 RUILicenseKeyType.unknown and the four status flags (blacklisted, whitelisted, expired, activated) to RUILicenseKeyStatus.no. The license array has size, indexes and values as specified in RUISDKCS.cs.
Note:The order of the license array data has changed from the Usage Intelligence SDK V4.
The RUISDK.SetLicenseKey function can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.
The RUISDK.SetLicenseKey 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).
The RUISDK.SetLicenseKey function 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 function is very similar to the RUISDK.CheckLicenseKey function, however rather than just being a passive license check, it also registers the new key with the server and associates it with this particular client installation.
RUIResult RUISDK.SetLicenseKey (String newKey, out List<Int32> licenseArray, String sessionID = “”)
Parameters
The RUISDK.SetLicenseKey function has the following parameters.
|
Parameter |
Description |
|||||||||
|
licenseKey (String) |
The license key to be checked. This value cannot be empty. The function accepts a String parameter that is the license key itself and a List<Int32> 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 from the RUILicenseKeyIndex enum: typeIndex (0) expiredIndex (1) activeIndex (2) blacklistedIndex (3) whitelistedIndex (4) Each of the values 1 through 5 will be set to either 0 or 1 that refers to false or true respectively. The first value (RUILicenseKeyIndex.typeIndex) 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 from the RUILicenseKeyType enum: unchanged (-1) - Key Type is Unchanged (when in parameter) or Unknown (when out parameter) evaluation (0) purchased (1) freeware (2) unknown (3) nfr (4) - Key Type is Not For Resale custom1 (5) custom2 (6) custom3 (7) The following are the possible key status values:
|
|||||||||
|
licenseArray (List<Int32> of length 5) |
The vector that will be filled to contain the license status flags. |
|||||||||
|
sessionID (String) |
An optional session ID complying with above usage (content conditioning and validation rules in RUISDK.StartSession). Different from the V4 of the Usage Intelligence SDK, a sessionID parameter can be supplied (based on RUISDK.CreateConfig multi session value):
|
Returns
The RUISDK.SetLicenseKey function returns a RUIResult enum value with the following possible values.
|
Return |
Description |
|
ok |
Function successful. |
|
sdkInternalErrorFatal |
Irrecoverable internal fatal error. No further API calls should be made. |
|
sdkAborted |
A required New Registration has failed, and hence the SDK is aborted. RUISDK.StopSDK and RUISDK destructor are possible. |
|
suspended |
Instance has been instructed by Server to back-off. Will return to Running once back-off cleared. |
|
permanentlyDisabled |
Instance has been instructed by Server to disable. This is permanent, irrecoverable state. |
|
sdkOptedOut |
Instance has been instructed by the application to opt-out. |
|
configNotCreated |
Function validation: Configuration has not been successfully created. |
|
sdkNotStarted |
Function validation: SDK has not been successfully started. |
|
sdkAlreadyStopped |
Function validation: SDK has already been successfully stopped. |
|
invalidParameterExpectedNonEmpty |
Some API parameter is expected to be non-empty, and is not. |
|
timeThresholdNotReached |
Function validation: The API call frequency threshold (set by the Server) has not been reached. |
|
networkConnectionError |
Not able to reach the Server. |
|
networkServerError |
Error while communicating with the Server. |
|
networkResponseInvalid |
Message format error while communicating with the Server. |
Code Example
//Register a new license key
bool useDefaultReachOutHandler = false;
RUISDK mySDK = new RUISDK(useDefaultReachOutHandler); //...; //Creation and initialization shown in other snippets.
String myProductKey = "xyz";
List<Int32> licenseResult;
RUIResult rc = mySDK.SetLicenseKey(myProductKey, out licenseResult);
if(rc == RUIResult.ok)
{
if (licenseResult[(Int32)RUILicenseKeyIndex.typeIndex] == (Int32)RUILicenseKeyType.unchanged) {
MessageBox.Show("License Key is unchanged");
} else {
String myType = "License type = " + (licenseResult[(Int32)RUILicenseKeyIndex.typeIndex]).ToString();
MessageBox.Show(myType);
}
//Check if the license key is activated
if (licenseResult[(Int32)RUILicenseKeyIndex.activeIndex] == (Int32)RUILicenseKeyStatus.yes){
MessageBox.Show("License Active");
} else if (licenseResult[(Int32)RUILicenseKeyIndex.activeIndex] == (Int32)RUILicenseKeyStatus.no) {
MessageBox.Show("License Inactive");
} else {
MessageBox.Show("License status unknown");
}
//check if license key is blacklisted
if (licenseResult[(Int32)RUILicenseKeyIndex.blacklistedIndex] == (Int32)RUILicenseKeyStatus.yes){
MessageBox.Show("Key is black listed");
} else if (licenseResult[(Int32)RUILicenseKeyIndex.blacklistedIndex] == (Int32)RUILicenseKeyStatus.no) {
MessageBox.Show("Key is NOT black listed");
} else {
MessageBox.Show("Key blank listed status is unknown");
}
//Check if license key is expired
if (licenseResult[(Int32)RUILicenseKeyIndex.expiredIndex] == (Int32)RUILicenseKeyStatus.yes){
MessageBox.Show("Key is expired");
} else if (licenseResult[(Int32)RUILicenseKeyIndex.expiredIndex] == (Int32)RUILicenseKeyStatus.no) {
MessageBox.Show("Key is NOT expired");
} else {
MessageBox.Show("Key expiration status is unknown");
}
//Check if license key is white listed
if (licenseResult[(Int32)RUILicenseKeyIndex.whitelistedIndex] == (Int32)RUILicenseKeyStatus.yes){
MessageBox.Show("Key is white listed");
} else if (licenseResult[(Int32)RUILicenseKeyIndex.whitelistedIndex] == (Int32)RUILicenseKeyStatus.no) {
MessageBox.Show("Key is NOT white listed");
} else {
MessageBox.Show("Key white listed status is unknown");
}
} else {
MessageBox.Show("Failed to invoke function RUISDK.setLicenseKey()");
}