sntl_licensing_login_attr

Library Information

>This API belongs to the Sentinel RMS licensing library.

>The corresponding header is licensing.h.

Description

This API is a variant of the sntl_licensing_login function, which allows passing additional values for specific purposes at the time of obtaining a license authorization.

NOTE For Lease mode, if the entitlement is not obtained, then as a workaround, the transfer API should be called followed by lease job synchronization query type.

Syntax


SNTL_DECLARE(sntl_status_t) sntl_licensing_login_attr(sntl_licensing_app_context_t         *app_context,
                                                      const char                           *feature_name,
                                                      const sntl_licensing_attr_t          *attr,
                                                      sntl_licensing_login_session_t       **login_session);

Argument	Description
app_context [in]	Pointer to the application context object.
feature_name [in]	Name of the feature.
attr [in]	Pointer to the attribute object. The attributes that can be set are described below. If NULL is passed as the value of this parameter, this API will be equivalent to sntl_licensing_login API.
login_session [out]	Session object for the login request. This object can be used for updating and releasing the license authorization.

Attributes

The table below provides details about the attributes that can be set (using the sntl_licensing_attr_set API):

#	Attribute for...	Key and Description
1	Setting the feature version	> Attribute Key - SNTL_ATTR_LOGIN_FEATURE_VERSION >This attribute is used for setting the version associated with the feature. >You can specify a string value consisting of up to 11 alphanumeric characters.
2	Setting the units required	> Attribute Key - SNTL_ATTR_LOGIN_UNITS_REQUIRED >This attribute is used for setting the number of license tokens required. The License Manager verifies that the requested number of units exist and may reserve those units. >You can specify a numeric value not exceeding INT_MAX. >From RMS v9.5, license hard limit up to 4,294,967,294 is supported. This is applicable to license version 20 and above.
3	Setting the vendor usage data	>Attribute Key - SNTL_ATTR_LOGIN_VENDOR_USAGE_DATA >This attribute is used for setting the vendor data to be recorded in the usage log file. >You can specify a string consisting of up to 255 characters, including letters, numbers, and special characters and excluding number sign (#) and comma (,) as these are reserved characters. The following points are applicable to Sentinel RMS usage log only: >Only up to 100 characters are shown in the usage vendor log (even when a longer string is specified). > The vendor usage data set in the login API will reflect in login API's usage entry. The same vendorUsageData will be copied to the vendorUsageData field of other API calls, if not set in them. >If vendor usage data attribute consists of multiple words, each will be anonymized individually, only if they are separated using a space. In general, avoid specifying the same entry (or word) twice in the vendor usage data attribute as the "uniquely" anonymized data will be repeated. >The spaces in the vendor usage data attribute are replaced with underscores (_). Also, the keyword <an> itself is not anonymized and is replaced by an underscore (_) in the resulting usage log line record. >To complete the vendor usage data attribute anonymization process, the system administrator must have also allowed anonymity of user information (either by setting the LS_LOG_ANONYMITY environment variable or using the -log-anonymity License Manager start-up option). The following points are applicable for SCL Add-on for RMS: >The entire string, with the maximum allowed length of 255 characters, is shown in the usage vendor log. >From RMS 9.7 onwards, the vendor usage data set in the login API will reflect in login API's usage entry only. This data will not be copied for any other API's usage records.
4	Setting the usage count multiplier	>Attribute Key - SNTL_ATTR_LOGIN_USAGE_COUNT_MULTIPLIER >This attribute is applicable to the Lease mode. >The value passed using this attribute is known as the login usage count multiplier. >The usage count value is defined by the vendor to calculate usage during a particular licensing session. Usually, each session consumes one countª per a login-refresh-logout call sequence. At times, vendor may want to represent this consumption differently, then a usage count multiplier value can be specified—at the start of the session (login), update (refresh), and its end (logout). >For a particular session, login, refresh, and logout usage count values will be added (by Sentinel EMS end) to calculate the usage count multiplier for reports generation and billing purposes. >You can specify only positive numeric values, not exceeding INT_MAX, as the usage count multiplier.
5	Setting the disable broadcast during grace period	> Attribute Key - SNTL_ATTR_LOGIN_DISABLE_GRACE_BROADCAST >Introduced in v9.2.0, this attribute is used for stopping the network broadcasts (looking for a License Manager with licenses) in the case of grace licenses. > By default, the client library performs a network broadcast. >The allowed value is SNTL_ATTR_YES - The network broadcast for checking the network license availability is disabled.
6	Settings for creating a Zombie login session using a login call	>Attribute Key - SNTL_ATTR_LOGIN_ZOMBIE_SESSION >This attribute is set to create a zombie session at login call. >The allowed value for this attribute is SNTL_ATTR_YES
7	Configuring the client machine identifier criteria	Attribute Key - SNTL_ATTR_LOGIN_ZOMBIE_SESSION_IDENTIFIER_MASK Possible values of the client identifier mask: SNTL_ZOMBIE_SESSION_IDENTIFIER_HOSTNAME SNTL_ZOMBIE_SESSION_IDENTIFIER_USERNAME SNTL_ZOMBIE_SESSION_IDENTIFIER_MACHINE_FINGERPRINT SNTL_ZOMBIE_SESSION_IDENTIFIER_ALL >This attribute cleans up all the sessions (zombie sessions included) based on the client identifier mentioned above. >If no identifier is specified then the default value (SNTL_ZOMBIE_SESSION_IDENTIFIER_ALL) will be used. >To close zombie sessions for all the features from the current machine, the keyword "$" should be used instead of the feature name in the feature name parameter defined for the login_attr API. NOTE Convert the required client machine identifier mask value to a string before passing it as an input.
8	Setting the challenge data	This attribute specifies the challenge data used by the client application to challenge the License Manager. >Attribute Key - SNTL_ATTR_LOGIN_CHALLENGE_DATA >You can specify a string consisting up to 30 characters (A-Z, a-z, and 0-9 only).
9	Setting the challenge secret	> Attribute Key - SNTL_ATTR_LOGIN_CHALLENGE_SECRET >This attribute specifies the index of the challenge secret that the client application expects the License Manager to use in order to respond to the challenge. >You may also see: Coding the Challenge-Response Mechanism >This value may range from 1 to the number of secrets provided in the license.
10	Setting the vendor-specific identifier	> Attribute Key - SNTL_ATTR_LOGIN_VENDOR_ISOLATION_IDENTIFIER >This attribute is used for setting the vendor identifier that was used for the customized vendor isolated License Manager. This identifier is used to distinguish the vendor isolated License Manager from the generic License Manager. To learn more about the Isolated License Managers, refer to the corresponding Chapter in the Sentinel RMS SDK Developer Guide. >You can specify a string value consisting of up to 25 alphanumeric characters.
11	Setting the grace error notification	> Attribute Key - SNTL_ATTR_LOGIN_IGNORE_GRACE_ERROR >This attribute is used for setting the error notification behavior if error(s) are encountered during the installation of a grace license. >The allowed values are: •SNTL_ATTR_YES (the default setting) - Any error encountered during the installation of a grace license will be ignored. •SNTL_ATTR_NO - Any error encountered during the installation of a grace license will be notified.
12	Setting the login identity string	> Attribute Key - SNTL_ATTR_LOGIN_IDENTITY_STRING >This attribute is used for setting the string retrieved from the identity object created using the sntl_licensing_identity_serialize API.

a. Unless this count value has been modified using the SNTL_ATTR_LOGIN_UNITS_REQUIRED attribute.

NOTE You may instead use the macros (which are wrappers to the sntl_licensing_login_attr API) for setting the login attributes. For example, 'sntl_licensing_attr_set_feature_version' is the macro for setting the version corresponding to the feature. You can find more macros for setting attributes in the licensing.h header file.

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.