ApplicationContext Class

An application context object contains the configuration settings that should be used by the licensing API calls made using that application context object. The class also initializes and allocates resources necessary for the RMS licensing library.

Constructors

Syntax Description
ApplicationContext ()

Default constructor of the
ApplicationContext class. Creates an ApplicationContext object.

ApplicationContext (int vendorId) Creates an object of the ApplicationContext class for a specific vendor ID. Set 0 as the value of the vendorId.
ApplicationContext (Attribute attribute) Creates an object of the ApplicationContext class that defines various client configuration and licensing attributes.
ApplicationContext (int vendorId, Attribute attribute)

Creates an object of the ApplicationContext class for a specific vendor ID. Also defines various client configuration and licensing attributes. Set 0 as the value of the vendorId.

Attribute

The following table provides details about attributes that can be set as a part of the constructor:

# Attribute for... Key and Description
1 Setting the License Manager Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

> Attribute Key - SNTL_ATTR_APPCONTEXT_CONTACT_SERVER.

>Specify the values for setting the License Manager. In the case of:

On-premises and Standalone Lease mode, NO-NET is to be set (NO-NET, NO_NET, no_net, and no-net are synonymous).

On-premises and Network Lease mode, set Hostname or IP address of the machine where the License Manager is installed. Alternatively, the License Manager name can be set using the LSHOST or the LSFORCEHOST environment variables.

Connected (Cloud LM) licensing, set sntl-cloudlm.

NOTE   You may use the macro, SNTL_CLOUDLM, for setting the License Manager in Cloud. You can find this macro in the licensing.h header file.

>Alternatively, the License Manager name can be set using the LSHOST or the LSFORCEHOST environment variables.

>If no License Manager name is set, the application looks for the license first on the local computer, and then it will make a broadcast (applicable for Standalone and Network), looking for License Managers in the subnet, for a license. The application will not look for a license in the Connected (Cloud LM) deployment.

2 Enabling/Disabling Auto refresh Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_AUTO_REFRESH.

>This attribute is used for enabling/disabling the automatic license refresh process.

>The allowed values are:

SNTL_ATTR_YES (the default setting) - The license sessions will be refreshed automatically without having to call the refresh API.

SNTL_ATTR_NO - The license sessions will need to refreshed manually, by calling the refresh API.

NOTE   By default, auto-refresh is enabled. Up to v9.1.0, this functionality was not supported for Windows Console applications.

3 Enabling/Disabling Local Renewal Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_ENABLE_LOCAL_RENEWAL.

>This attribute is used for enabling\disabling the local renewal of the license authorization. Refer to the section "Deciding License Token Lifetime" of Chapter - Planning
Application Licensing in the Sentinel RMS SDK Developer Guide for details.

>The allowed values are:

SNTL_ATTR_YES (the default setting) - Allows renewal of a network license locally (no check with the License Manager) within the first 80% of the lifetime of the license.

NOTE   When auto-refresh is enabled, it is recommended to turn off local renewal.

SNTL_ATTR_NO - Does not allow local renewal of the network license, instead requests to go to the License Manager that issued the license.

4 Controlling Remote Sessions Supported in On-premises modeSupported in Lease mode

> Attribute Key - SNTL_ATTR_APPCONTEXT_CONTROL_REMOTE_SESSION.

>This attribute is used for setting the behavior for applications accessed using remote sessions in the standalone licensing environments. The allowed values are:

SNTL_CONTROL_REMOTE_BOTH_TYPES - Access not allowed through both the terminal sessions and RDP connections.

SNTL_CONTROL_REMOTE_ONLY_TERMINAL - Access not allowed through terminal sessions, but allowed through RDP connections (the default setting).

SNTL_CONTROL_REMOTE_NONE - Access allowed through both the terminal sessions and RDP connections.

5 Setting the Minimum Signing Key Index Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

Attribute Key - SNTL_ATTR_APPCONTEXT_MINIMUM_SIGNING_KEY_INDEX.

This attribute is used for setting the minimum signing key index preferences for using RMS licenses.

The allowed values are:

>SNTL_RSA_SIGNING_KEY_INDEX - The signing key index for restricting license consumption to the more secure RSA-signed licenses (version 18 and above). This is the default value.

>SNTL_AES_SIGNING_KEY_INDEX - The signing key index for allowing consumption of licenses of all versions, including the AES encrypted licenses (version 17 and below).

For more information about the license security enhancements provided with version 18 or higher licenses, refer to the Sentinel RMS SDK Developer Guide.

6 Setting the Contact Server List Supported in On-premises modeSupported in Lease mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_CONTACT_SERVER_LIST.

>This attribute provides a list of License Managers. If the SNTL_ATTR_APPCONTEXT_CONTACT_SERVER attribute or LSFORCEHOST variable is not set, preference is given to this list for searching the License Manager.

>The License Managers are provided as a ‘~’ separated list. For example:

      “<License Manager Address1>~<License Manager          Address2>~....<License Manager AddressN>”.

>The License Manager address could be IP address or hostname.

>If a License Manager list is specified using this attribute, the License Manager list set using the LSHOST environment variable is ignored.

>If the SNTL_ATTR_APPCONTEXT_CONTACT_SERVER attribute or LSFORCEHOST variable is set, the License Manager list specified using this attribute is ignored.

>These License Managers may not be a part of the same subnet.

7 Setting the License Manager Port Supported in On-premises modeSupported in Lease mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_SERVER_PORT.

>This attribute is used for setting the network port—other than 5093—for communicating with the License Manager.

>5093 is the default port number.

8 Setting Host Name Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

> Attribute Key - SNTL_ATTR_APPCONTEXT_HOSTNAME.

>This attribute is used for defining a customized host name in place of the actual host name (in the usage logs).

>The maximum length of the string is 31 characters. The standard character set includes letters, numbers, and the following symbols:

% (percentage)

. (period)

- (hyphen)

_(underscore).

9 Setting the X Display Name Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_XDISPLAYNAME.

>This attribute is used for setting the name of the X display where the user needs to display the application. It is used as a license sharing criteria by the License Manager in order to determine the eligibility of a new client.

>The maximum length of the string is 31 characters. The standard character set includes letters, numbers, and the following symbols:

% (percentage)

. (period)

- (hyphen)

_(underscore).

10 Setting the Broadcast Interval Supported in On-premises modeSupported in Lease mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_BROADCAST_INTERVAL.

>This attribute is used for setting the timeout interval (in seconds) to find a License Manager in the subnet.

>If a licensed application performs a broadcast to establish the presence of a License Manager on the subnet, it makes two broadcast attempts, where the length of the second broadcast attempt is slightly longer than the first.

> If the broadcast attempt fails, then an error is returned, after waiting for the interval period set.

> The default value of broadcast interval is 9 seconds.

11 Enabling Exhaustive BroadcastSupported in On-premises modeSupported in Lease mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_ENABLE_EXHAUSTIVE_BROADCAST.

>This attribute is used to specify the discovery mechanism for License Managers.

>The allowed values are:

SNTL_ATTR_NO (default) – Configure the licensing application to wait for a response from the first license manager that is included in the contact server list. If any license manager (in the list) does not respond, then the license manager responding first (outside the list) is designated as the contact server.

SNTL_ATTR_YES - This option directs the client to exhaustively search for the License Managers for the entire broadcast timeout interval. In this process a server responding later, but higher in the preferred list of License Managers, will be set as the contact server.

12 Setting the Timeout Interval Supported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

> Attribute Key - SNTL_ATTR_APPCONTEXT_NETWORK_TIMEOUT.

>This attribute is used for setting the timeout interval (in seconds) for communication between the licensed application and the License Manager. For example, when a licensed application sends a request to a License Manager and the License Manager does not respond, then it re-sends the message for few more times. Each time, the length of the timeout interval is slightly longer than the previous.

>These timeouts are different from the broadcast timeouts.

>The default value of interval is 30 seconds.

13 Setting the Vendor-defined ID for License SharingSupported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_VENDOR_DEFINED_ SHARINGID.

>This attribute is used for defining a string-based vendor-defined license sharing criteria.

>License Manager uses a default value "default-sharing-ID" for sharing, which is a vendor-defined sharing ID.

>The maximum length of the string is 31 characters. The standard character set includes letters, numbers, and the following symbols:

% (percentage)

. (period)

- (hyphen)

_(underscore).

14 Enabling/Disabling Grace Supported in On-premises modeSupported in Lease mode

> Attribute Key - SNTL_ATTR_APPCONTEXT_REQUEST_GRACE.

>This attribute is used for enabling/disabling the grace period. The allowed values are:

SNTL_ATTR_YES (the default setting) - Allows switching to grace period in the state of network disconnect.

SNTL_ATTR_NO - Does not switch to grace period in the state of network disconnect.

15 Enabling/Disabling Default Error HandlerSupported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

>Attribute Key - SNTL_ATTR_APPCONTEXT_DEFAULT_ERROR_HANDLER.

>The default error handler is a simple function that display error messages and code about the situation that caused the error condition.

>If the default error handler is not being used, the call returns the status code of the latest error condition. In that case, make sure to check the returned value before proceeding.

>This attribute is used for enabling/disabling the default error handler. The allowed values are:

SNTL_ATTR_YES - Performs default error handling whenever the error condition occurs.

SNTL_ATTR_NO (the default setting) - Does not perform default error handling whenever the error condition occurs.

16 Setting Trace LevelSupported in On-premises modeSupported in Lease modeSupported in Connected (Cloud LM) mode

NOTE   Starting v9.3.0, this attribute has been deprecated. For setting the trace level, use the sntl_licensing_configure API.

>Attribute Key - SNTL_ATTR_APPCONTEXT_TRACE_LEVEL.

>This attribute is used for setting the trace level. By default, no tracing is performed.

>The allowed values are:

SNTL_TRACE_FUNCTION - Traces the major licensing API functions. The parameters and status codes of the functions are logged.

SNTL _TRACE_LICENSE - Traces the license keys.

SNTL_TRACE_ERROR - Traces the errors encountered on run-time.

SNTL _TRACE_ALL - Traces all of the above operations.

NOTE   Convert the required trace level value to a string before passing it as an input.

API

Modifier and Type API
String

transfer(String action, String scope, Attribute attribute, String recipient) throws LicensingException.

String install(String installData, Attribute attribute) throws LicensingException.
String getInfo(String scope, String query) throws LicensingException.
void dispose() throws LicensingException.
void registerCallback(ApplicationContext appContext, String type, ICallback cbObject) throws LicensingException.
String uninstall(String uninstallData) throws LicensingException.