refresh

void refresh()
void refresh(Attribute attribute)

This API renews the license authorization by contacting the Sentinel Cloud Connect.

>The refresh call should be placed after the login call.

>The refresh API call is synchronous and is sent to the Sentinel Cloud Connect instantly.

Additional Details

The refresh API performs the following functions:

>Avoids premature termination of concurrent sessions: This API refreshes the concurrent sessions periodically to keep the sessions alive for a longer period. Refreshing a session ensures that the background process does not kill the session after a specified time.

>Notifies an application about terminated sessions:This API helps identify if a concurrent session has been terminated or is still valid. For example, If a session is killed by a background process or a vendor's administrator, the API returns an error and the application does not allow the user to consume the feature further avoiding the license overuse.

>Cleans abandoned sessions: The background process checks for the presence of abandoned sessions and closes them. An abandoned session is the one where the logout and refresh API calls do not reach the Sentinel Cloud Connect, for example, in the case of browser crash. This way the background process cleans abandoned sessions and makes the concurrency available for consumption.

>Helps in usage tracking: The abandoned sessions are forced complete to ensure integrity of usage data.

>Determines the duration of a session: Let us say an application ran for 1 month and then crashed suddenly. The last refresh time of the application will help to take into account the entire duration for which the application ran, and bill the customer for the same.

For more details about abandoned sessions, see License Session Timeout (mins).

When to use the refresh API?

The licensed application should call this API periodically for refreshing sessions.

For example, if the application allows online movie watching, then the application brings buffer only for certain duration, then it fetches next buffer for next duration, and so on. The application calls the refresh API and fetches the next buffer only if the session is still valid.

If a user exits the browser without proper logout or due to any reason, the refresh API will return failure, and the background process will auto-complete the session to free the concurrency.

You need to set certain configurations for background process so that it can identify abandoned sessions and force them complete to free the concurrency.

Parameters

Parameter	Description
attribute [in]	The attribute object. Reserved for future use. Use NULL as the value for this argument.

Parameter

Description

attribute [in]

The attribute object.

Reserved for future use. Use NULL as the value for this argument.

Attributes

The table below provides details about the attributes that can be set by using the LicensingConstants class:

Attribute for...	Key and Description
Setting the usage count multiplier	> Attribute Key - SNTL_ATTR_REFRESH_USAGE_ COUNT_MULTIPLIER >Optional >This attribute is used to specify the number of usage count to be consumed or returned in a refresh session. >By default, a login-logout session consumes one usage count and this count is acknowledged during the login call. At times, a vendor may want to specify a count more than one, either at the start of the session (login) and/or at its end (logout). To consume a usage count more than one for a given session, set the usage count multiplier. A negative value can also be specified to return the unconsumed count at the refresh time. NOTE It is recommended not to use the logout API to pass usage count multiplier for licenses where the usage limit is defined. >Its value can be any integer in the range of -2,147,483,647 to 2,147,483,647. The default value is 1 for the login API and 0 for the logout and refresh APIs. NOTE You cannot provide the 0 value explicitly in the usage count multiplier of logout and refresh APIs. > The total usage count for a particular session is calculated by adding the usage count multiplier values specified in the login, refresh, and logout APIs. By default, a login-refresh-logout combination consumes one (1+0+0) usage count. >The usage count multiplier value is used for licenses where usage limit is defined. The usage count multiplier value cannot exceed the sum of usage limit and grace limit. >The negative usage count multiplier value must be equal to or less than the total usage count passed in a session till refresh/logout. Otherwise the refresh API returns an error. >The usage count consumed by a session is visible in all EMS reports.

Attribute for...

Key and Description

Setting the usage count multiplier

> Attribute Key - SNTL_ATTR_REFRESH_USAGE_ COUNT_MULTIPLIER

>Optional

>This attribute is used to specify the number of usage count to be consumed or returned in a refresh session.

>By default, a login-logout session consumes one usage count and this count is acknowledged during the login call. At times, a vendor may want to specify a count more than one, either at the start of the session (login) and/or at its end (logout). To consume a usage count more than one for a given session, set the usage count multiplier. A negative value can also be specified to return the unconsumed count at the refresh time.

NOTE It is recommended not to use the logout API to pass usage count multiplier for licenses where the usage limit is defined.

>Its value can be any integer in the range of -2,147,483,647 to 2,147,483,647. The default value is 1 for the login API and 0 for the logout and refresh APIs.

NOTE You cannot provide the 0 value explicitly in the usage count multiplier of logout and refresh APIs.

> The total usage count for a particular session is calculated by adding the usage count multiplier values specified in the login, refresh, and logout APIs. By default, a login-refresh-logout combination consumes one (1+0+0) usage count.

>The usage count multiplier value is used for licenses where usage limit is defined. The usage count multiplier value cannot exceed the sum of usage limit and grace limit.

>The negative usage count multiplier value must be equal to or less than the total usage count passed in a session till refresh/logout. Otherwise the refresh API returns an error.

>The usage count consumed by a session is visible in all EMS reports.

Exception Handling

If unsuccessful, throws LicensingException.