Setting the Current License to the Supplied License Key
The setLicenseKey() function checks the Server for the license data for the supplied licenseKey and sets the current license to licenseKey.
Whereas checkLicenseKey() is a passive check, setLicenseKey() 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 RUIKeyType.unknown and the four status flags (blocked, allowed, expired, activated) to RUIKeyStatus.no. The license array has size, indexes and values.
The order of the license array data has changed from the Usage Intelligence SDK V4.
The setLicenseKey() function can be called between startSDK() and stopSDK(), and can be called zero or more times.
The 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 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. blocked or allowed), active, or expired. The function is very similar to the 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 setLicenseKey(String newKey, List<RUIKeyData> licenseArray)
RUIResult setLicenseKey(String newKey, List<RUIKeyData> licenseArray, String SessionID)
Parameters
The 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<RUIKeyData> 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 RUIKeyIndex enum: LICENSE_ARRAY_INDEX_KEY_TYPE (0) LICENSE_ARRAY_INDEX_KEY_EXPIRED (1) LICENSE_ARRAY_INDEX_KEY_ACTIVE (2) LICENSE_ARRAY_INDEX_KEY_BLOCKED (3) LICENSE_ARRAY_INDEX_KEY_ALLOWED (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 (RUIKeyIndex.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 RUIKeyType enum: UNCHANGED (-1) 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 from the RUIKeyStatus enum:
|
|||||||||
|
licenseArray (List<int> 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 startSession()). Different from the V4 of the Usage Intelligence SDK, a sessionID parameter can be supplied (based on createConfig() multi session value):
|
Returns
The setLicenseKey() function returns one of the RUIState enum values below:
|
Return |
Description |
|
OK |
Function successful. |
|
SDK_INTERNAL_ERROR_FATAL |
Irrecoverable internal fatal error. No further API calls should be made. |
|
SDK_ABORTED |
A required New Registration has failed, and hence the SDK is aborted. stopSDK() is possible. |
|
SDK_PERMANENTLY_DISABLED |
The Server has instructed a permanent disable. |
|
SDK_SUSPENDED |
The Server has instructed a temporary back-off. |
|
SDK_OPTED_OUT |
Instance has been instructed by the application to opt-out. |
|
CONFIG_NOT_CREATED |
Configuration has not been successfully created. |
|
SDK_ALREADY_STOPPED |
SDK has already been successfully stopped. |
|
SDK_NOT_STARTED |
SDK has not been successfully started. |
|
INVALID_PARAMETER_EXPECTED_NON_EMPTY |
Some API parameter is expected to be non-empty, and is not. |
|
TIME_THRESHOLD_NOT_REACHED |
The API call frequency threshold (set by the Server) has not been reached. |
|
NETWORK_CONNECT_ERROR |
Not able to reach the Server. |
|
NETWORK_SERVER_ERROR |
Error while communicating with the Server. |
|
NETWORK_RESPONSE_INVALID |
Message format error while communicating with the Server. |
Code Example
//Register a new license key
booleanuseDefaultReachOutHandler = false;
RUISDK mySDK = new SDKImpl(useDefaultReachOutHandler); //...; //Creation and initialization shown in other snippets.
String myProductKey = "xyz";
List<RUIKeyData> licenseResult = new ArrayList<>(5);
RUIResult rc = mySDK.setLicenseKey(myProductKey, licenseResult);
if(rc == RUIResult.OK)
{
if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_TYPE) == RUIKeyType.UNCHANGED) {
System.out.println("License Key is unchanged");
} else {
String myType = "License type = " + licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_TYPE).getId();
System.out.println(myType);
}
//Check if the license key is activated
if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_ACTIVE) == RUIKeyStatus.YES){
System.out.println("License Active");
} else if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_ACTIVE) == RUIKeyStatus.NO) {
System.out.println("License Inactive");
} else {
System.out.println("License status unknown");
}
//check if license key is blocked
if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_BLOCKED) == RUIKeyStatus.YES){
System.out.println("Key is blocked");
} else if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_BLOCKED) == RUIKeyStatus.NO) {
System.out.println("Key is NOT blocked");
} else {
System.out.println("Key blocked status is unknown");
}
//Check if license key is expired
if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_EXPIRED) == RUIKeyStatus.YES){
System.out.println("Key is expired");
} else if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_EXPIRED) == RUIKeyStatus.NO) {
System.out.println("Key is NOT expired");
} else {
System.out.println("Key expiration status is unknown");
}
//Check if license key is allowed
if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_ALLOWED) == RUIKeyStatus.YES){
System.out.println("Key is allowed");
} else if (licenseResult.get(RUISDK.LICENSE_ARRAY_INDEX_KEY_ALLOWED) == RUIKeyStatus.NO) {
System.out.println("Key is NOT on allowed list");
} else {
System.out.println("Key allowed status is unknown");
}
} else {
System.out.println("Failed to invoke function setLicenseKey()");
}