Common Use Cases
This section provides examples on how to use Unified APIs to perform the common licensing tasks, such as:
>Coding a standard license authorization request
>Coding a refresh license authorization request
>Finding the expiration date, usability status, and available usage count of a license
Coding a standard license authorization request
After creating an entitlement in EMS for the Connected mode, a developer needs to perform the following steps to allow license consumption from an end user’s machine.
1.Create an Application Context.
2.Set the license attributes for login.
3. Create an instance of the LoginSession class and call the login API.
4.After performing the required operation, call the logout API (with the logout attributes).
Sample Code
void SampleLoginCall()
{
ApplicationContext appContext;
/* Initialize application context */
appContext = new ApplicationContext(null);
/* Generate Identity string */
String customer = "SampleCustomer";
String user = "SampleUser";
String featureName = "f1";
String featureVersion = "SampleFeatVer";
String usageCountLogin = "1";
String vendorData = "Dummy data";
SentinelCloud.Services.Licensing.Attribute identityAttributes = new SentinelCloud.Services.Licensing.Attribute();
identityAttributes.set(LicensingConstants.SNTL_ATTR_IDENTITY_CUSTOMER_ID, customer);
identityAttributes.set(LicensingConstants.SNTL_ATTR_IDENTITY_USERNAME, user);
String identity = new Identity(appContext, identityAttributes).serialize();
/* Set Login attributes */
SentinelCloud.Services.Licensing.Attribute loginAttributes = new SentinelCloud.Services.Licensing.Attribute();
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_IDENTITY_STRING, identity);
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_VENDOR_USAGE_DATA, vendorData);
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_FEATURE_VERSION, featureVersion);
loginAttributes.set(LicensingConstants. SNTL_ATTR_LOGIN_USAGE_COUNT_MULTIPLIER, usageCountLogin);
LoginSession loginSession = new LoginSession();
/* Perform license authorization call */
loginSession.login(appContext, featureName, loginAttributes);
/* store session handle for reference when we will call refresh or logout API */
String sessionHandle = loginSession.serialize();
}
/* argument is session handle that we have got from the loginSession instance by calling loginSession.serialize() */
void SampleDefaultLogoutCall(String sessionHandle)
{
ApplicationContext appContext;
LoginSession logoutSession = new LoginSession(null, sessionHandle);
/* default logout call */
logoutSession.logout();
}
/* argument is session handle that we have got from the loginSession instance by calling loginSession.serialize() */
void SampleLogoutCall(String sessionHandle)
{
ApplicationContext appContext;
/* set logout attributes */
SentinelCloud.Services.Licensing.Attribute logoutAttributes = new SentinelCloud.Services.Licensing.Attribute();
logoutAttributes.set(LicensingConstants.SNTL_ATTR_LOGOUT_USAGE_COUNT_MULTIPLIER, "100");
LoginSession logoutSession = new LoginSession(null, sessionHandle);
/* logout call */
logoutSession.logout(logoutAttributes);
}Coding a refresh license authorization request
The refresh API refreshes a license state on the Sentinel Cloud Connect server. The refresh API calls are placed between login and logout API calls to secure the license consumption state.
After creating an entitlement in EMS for the Connected mode, a developer needs to perform the following steps to allow license consumption from an end user’s machine.
1.Create an Application Context.
2.Set the license attributes for login.
3. Create an instance of the LoginSession class and call the login API.
4.Call the refresh API at appropriate intervals to refresh the license state.
NOTE The refresh API intervals are configured in such a way that login sessions do not get killed by the background process. The refresh intervals can be configured by using the Session Timeout (with Refresh) property. You need to contact our Support Team to customize these configurations.
Sample Code
void SampleLoginCall()
{
ApplicationContext appContext;
/* Initialize application context */
appContext = new ApplicationContext(null);
/* Generate Identity string */
String customer = "SampleCustomer";
String user = "SampleUser";
String featureName = "f1";
String featureVersion = "SampleFeatVer";
String usageCountLogin = "1";
String vendorData = "Dummy data";
SentinelCloud.Services.Licensing.Attribute identityAttributes = new SentinelCloud.Services.Licensing.Attribute();
identityAttributes.set(LicensingConstants.SNTL_ATTR_IDENTITY_CUSTOMER_ID, customer);
identityAttributes.set(LicensingConstants.SNTL_ATTR_IDENTITY_USERNAME, user);
String identity = new Identity(appContext, identityAttributes).serialize();
/* Set Login attributes */
SentinelCloud.Services.Licensing.Attribute loginAttributes = new SentinelCloud.Services.Licensing.Attribute();
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_IDENTITY_STRING, identity);
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_VENDOR_USAGE_DATA, vendorData);
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_FEATURE_VERSION, featureVersion);
loginAttributes.set(LicensingConstants.SNTL_ATTR_LOGIN_USAGE_COUNT_MULTIPLIER, usageCountLogin);
LoginSession loginSession = new LoginSession();
/* Perform license authorization call */
loginSession.login(appContext, featureName, loginAttributes);
/* store session handle for reference when we will call refresh or logout API */
String sessionHandle = loginSession.serialize();
}
/* argument is session handle that we have got from the loginSession instance by calling loginSession.serialize() */
void SampleDefaultRefreshCall(String sessionHandle)
{
ApplicationContext appContext;
/* refresh call */
LoginSession refreshSession = new LoginSession(null, sessionHandle);
refreshSession.refresh();
}
/* argument is session handle that we have got from the loginSession instance by calling
loginSession.serialize() */
void SampleRefreshCall(String sessionHandle)
{
ApplicationContext appContext;
/* set refresh attributes */
Attribute refreshAttributes = new Attribute();
refreshAttributes.set(LicensingConstants.SNTL_ATTR_REFRESH_USAGE_COUNT_MULTIPLIER, "100");
LoginSession refreshSession = new LoginSession(null, sessionHandle);
/* refresh call */
refreshSession.refresh(refreshAttributes);
}
/* argument is session handle that we have got from the loginSession instance by calling loginSession.serialize() */
void SampleDefaultLogoutCall(String sessionHandle)
{
ApplicationContext appContext;
LoginSession logoutSession = new LoginSession(null, sessionHandle);
/* default logout call */
logoutSession.logout();
}
/* argument is session handle that we have got from the loginSession instance by calling loginSession.serialize() */
void SampleLogoutCall(String sessionHandle)
{
ApplicationContext appContext;
/* set logout attributes */
String usageCountLogout = "100";
SentinelCloud.Services.Licensing.Attribute logoutAttributes = new SentinelCloud.Services.Licensing.Attribute();
logoutAttributes.set(LicensingConstants.SNTL_ATTR_LOGOUT_USG_COUNT_MULTIPLIER, usageCountLogout);
LoginSession logoutSession = new LoginSession(null, sessionHandle);
/* logout call */
logoutSession.logout(logoutAttributes);
}Finding the expiration date, usability status, and available usage count of a license
Use the getInfo API to obtain license information from the cloud.
>Create an Application Context.
>Set the getInfo attributes.
>Using the Application Context created above, call the getInfo API.
Sample Code
// Variable declarations.
static ApplicationContext lsapiInstance = null;
String customer = "NamedCustomer";
String user = "user_1";
String featureName = "f1";
String featureVersion = "SampleFeatVer";
Attribute attrGetinfo = new Attribute();
String getInfoResponse = null;
// Create application Context
lsapiInstance = new ApplicationContext(null);
// Set identity attributes
Attribute attrIdentity = new Attribute();
attrIdentity.set(LicensingConstants.SNTL_ATTR_IDENTITY_CUSTOMER_ID, customer);
attrIdentity.set(LicensingConstants.SNTL_ATTR_IDENTITY_USERNAME, user);
Identity identity = new Identity(null, attrIdentity);
String identityLogin = identity.serialize();
String QueryFeatureInfo = "<sentinelQuery query=\"entitlementInfo\"/>";
String scopeFeatureInfo = new System.Text.StringBuilder("<?xml version=\"1.0\" encoding=\"UTF-8\"?>" + "<sentinelScope>" + "<identity>" + identityLogin + "</identity>" + "<feature index=\"0\">" + "<name>" + featureName + "</name>" + "<version>" + featureVersion + "</version>" + "</feature>" + "</sentinelScope>").ToString();
getInfoResponse = lsapiInstance.getInfo(attrGetinfo, scopeFeatureInfo, QueryFeatureInfo);
Console.Out.WriteLine("\n\nXML returned by getInfo: :\n\n" + getInfoResponse);Sample Output
The sentinelInfo structure contains the XML output of getInfo.
<sentinelInfo>
<entitlement>
<entitlementId>e1</entitlementId>
<product>
<productId>1</productId>
<productName>P1</productName>
<productVersion>1.0.0</productVersion>
<feature>
<featureId>12</featureId>
<featureName>calc</featureName>
<featureVersion>1.0.0</featureVersion>
<usable>true</usable>
<usabilityStatus>available</usabilityStatus>
<startDate>2012-07-31T00:00:00Z</startDate>
<endDate>2013-07-31T00:00:00Z</endDate>
<endDateGraceDuration>25</endDateGraceDuration>
<concurrencyCount>unlimited</concurrencyCount>
<usageCount>10</usageCount>
<usageCountConsumed>3</usageCountConsumed>
<usageCountGrace>10</usageCountGrace>
<vendorInfo>asdfsdf</vendorInfo>
</feature>
</product>
</entitlement>
</sentinelInfo>Parse the output XML to obtain the required license information, as described below: :
1.
To find the expiration date of a license, use endDate.
2.
To determine if the usage count is still available, use usageCount and usageCountConsumed.
In the case of licenses with a given usage limit:
Available units for consumption = (usageLimit+usageCountGrace)- usageCountConsumed
3.If the license has expired or the usage count has exhausted, the usabilityStatus will not be shown as available. In such cases, you can do one of the following (before calling the login API):
a.Reconfigure the entitlement (from EMS) to increase the end date or usage limit. You can also consider providing / increasing the grace limit.
b.Decide not to use the feature in the login call.