sntl_licensing_app_context_new

Library Information

>This API belongs to the Sentinel RMS licensing library.

>The corresponding header is licensing.h.

Description

Creates the application context object with the specified attributes. An application context object contains the configuration settings that should be used by the licensing API calls made using that application context object.

The function also initializes and allocates resources necessary for the RMS licensing library.

For Standalone Lease mode, the first call to this API also starts the process of obtaining the license lease from Sentinel Cloud Connect (SCC) onto the standalone machine (referred to as the lease job).

NOTE The lease job may take up to a few seconds or might fail to obtain a license. However, directly calling the login API without knowing the status of lease job, may result in failure. Use the syncLicenseJobInfo query before making the login call to check the status of the lease job.

Syntax

SNTL_DECLARE(sntl_status_t) sntl_licensing_app_context_new (sntl_uint32_t                    vendor_id,
                                                            sntl_licensing_attr_t            *attr,
                                                            sntl_licensing_app_context_t     **app_context);

Argument	Description
vendor_id [in]	Specify 0.
attr [in]	Pointer to the attribute object . The attributes that can be set are described below. Pass NULL to apply default attribute settings.
app_context [out]	Pointer to the application context created.

Argument

Description

vendor_id [in]

Specify 0.

attr [in]

Pointer to the attribute object .

The attributes that can be set are described below.

Pass NULL to apply default attribute settings.

app_context [out]

Pointer to the application context created.

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	> 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	>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 sntl_licensing_refresh API. • SNTL_ATTR_NO - The license sessions will need to refreshed manually, by calling the sntl_licensing_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	>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	> 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	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	>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	>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	> 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	>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	>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 Broadcast	>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	> 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. >These timeouts are different from the broadcast timeouts.
13	Setting the Vendor-defined ID for License Sharing	>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	> 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 Handler	>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 Level	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.

Returns

The status code SNTL_SUCCESS is returned, if successful. Otherwise, a specific status code is returned indicating the reason for failure.

For the complete list of error codes, refer to Licensing Library Error and Result Codes.