sntl_licensing_transfer

Library Information

>This API belongs to the Sentinel RMS licensing library.

>The corresponding header is licensing.h.

Description

Use this API for:

>Transferring a license authorization from the License Manager. Use the commute ( Supported in On-premises mode ) action tag for transferring a license authorization from the License Manager.

>Generating the acknowledgment string for returning the commuter authorization code. Use returnCommuter ( Supported in On-premises mode Supported in Lease mode ) action tag for generating the acknowledgment string.

>Synchronization between the licensed application \ License Manager and SCC. Use the sync ( Supported in Lease mode ) action for enforcing synchronization.

>Canceling an active lease to SCC so that it is available for other end users to use. Use the cancelLease ( Supported in Lease mode ) action.

>Resuming the canceled lease and request SCC for a new lease. Use the resumeLease ( Supported in Lease mode ) action.

>Marking the usage file containing usage data as completed. Use the readyUsageForUpload ( Supported in On-premises mode ) action.

See Also: Implementing Cancel Lease, Resume Lease, and Force Sync (C, Java, .NET)

Syntax

SNTL_DECLARE(sntl_status_t) sntl_licensing_transfer(sntl_licensing_app_context_t     *app_context,
                                                    const char                       *action,
                                                    const char                       *scope,
                                                    const sntl_licensing_attr_t      *attr,
                                                    const char                       *recipient,
                                                    char                             **info);

Parameters

Parameter Description

app_context [in] Pointer to the application context object.

action [in]

Type of transfer action as shown here.

Commute action

<commute>
  <featureName>"FEATURE_NAME"</featureName>  
  <featureVersion>"FEATURE_VERSION"</featureVersion>  
  <duration>1</duration>
</commute>

Tag

Description

The feature name of the license to be transferred.

Version associated with the feature.

>The number of days for which a license is transferred (checked-out) from the License Manager.

>Specify zero (0) for an unlimited check-out period, which is equal to number of checkout days allowed.

>If the remaining number of days is less than the requested number of days, then the duration parameter is ignored, and the License Manager issues a commuter authorization for the remaining number of days.

>The License Manager never issues commuter authorization beyond the birth and death date of the license. The start date of the commuter authorization is based on the client system’s time and not that of the License Manager.

Return commuter action

<returnCommuter>
   <featureName>"FEATURE_NAME"</featureName>
   <featureVersion>"FEATURE_VERSION"</featureVersion>
</returnCommuter>

Tag	Description
<featureName>	The feature name of the license to be returned.
<featureVersion>	Version associated with the feature.

Force synchronization action (Not available in API Builder)

<sync></sync>

Tag

Description

<sync>

Enforces synchronization between the licensed application / License Manager and Sentinel Cloud Connect to perform the following:

>Obtain lease from the Sentinel Cloud Connect to the licensed application \ License Manager.

>Transfer usage logs from the licensed application \ License
Manager to Sentinel Cloud Connect.

This tag is applicable to the Lease mode only.

Normally, this operation is not required to be called because:

>In Sentinel EMS when license-related attributes are changed, entitlement updates are delivered in the next update cycle.

> If you have made any changes in the lease renewal frequency, then the background process fetches lease and sends usage.

This operation is designed for users who prefer not to wait for periodic updates, allowing them to pull backend changes and push usage data instantly. It should be used judiciously and triggered manually, as it duplicates the resource-intensive background process.

Cancel Lease action (Not available in API Builder)

<cancelLease></cancelLease>

Tag

Description

>This tag is used to return the active lease (on the machine) and free up the quantity so that it can be made available for other customers.

>After the latest lease is canceled, old leases will stop functioning.

>Cancel lease acts on the complete machine. Post cancelation, all other applications installed on that machine will not be able to use the lease licenses.

>Cancel lease, introduced since the Sentinel RMS v9.4 release, is only available for the standalone lease deployment mode.

NOTE Standalone persistence must be initialized before performing the cancel and resume lease operations.

Resume Lease action (Not available in API Builder)

<resumeLease></resumeLease>

Tag

Description

>This tag is used to undo the effect of the cancel lease operation. In simple terms, after canceling an active lease, if an end user wants to use the lease license, then they are required to resume the lease.

>SCP will contact SCC and attempt to fetch a lease license that can be provided to the end user.

>Resume lease, introduced since the Sentinel RMS v9.4 release, is only available for the standalone lease deployment mode.

NOTE If the lease is resumed immediately after cancelation, it is possible that it may not start instantly. This can happen when the time difference between cancel and lease operations is less than one minute. In this scenario, you can use the syncLicenseJobInfo query type of the sntl_licensing_get_info API to check the status of the lease job. To get the lease, either wait till the next lease frequency or call the transfer sync API to get the lease instantly.

NOTE Standalone persistence must be initialized before performing the cancel and resume lease operations.

Ready Usage for Upload action (Not available in API Builder)

<readyUsageForUpload></readyUsageForUpload>

Tag

Description

>This tag is used to mark the current usage file (containing usage data) as completed so that it becomes ready for upload. After calling this API, completed usage file will be available at .

>Once this is done, the usage data generated by network and standalone licenses is ready to be uploaded to SCC.

>This tag is applicable only for users of SCL Add-on for RMS for the On-premises deployment mode.

scope [in]

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

attr [in]

The attribute object.

The attribute object contains attributes for Commute action type only:

Attribute for...	Key and Description
Setting units required	> Attribute Key - SNTL_ATTR_TRANSFER_UNITS_REQUIRED >This attribute is used for setting the number of license units required. >From RMS v9.5, license hard limit up to 4,294,967,294 is supported. This is applicable to license version 20 and above.
Setting locking criteria for commuter authorization	> Attribute Key - SNTL_ATTR_TRANSFER_LOCK_MASK >The locking criteria of the system for which the commuter authorization is requested. >Convert the required lock mask value to a string before passing it as an input.
Setting vendor usage data	> Attribute Key - SNTL_ATTR_TRANSFER_VENDOR_USAGE_DATA > This attribute is used for setting vendor data to be recorded in the usage file. It only tracks commuter authorization transfers from the License Manager, which are logged as "check-outs" in the usage file.
Setting extension days	> Attribute Key - SNTL_ATTR_TRANSFER_EXTENSION_IN_DAYS >This attribute is used for setting the number of days by which the commuter authorization period is to be extended.
Setting transfer identity	> Attribute Key - SNTL_ATTR_TRANSFER_IDENTITY_STRING >This attribute is used for specifying the identity.

recipient [in]

Recipient information of the machine for which the commuter authorization is requested.

Use the recipientInfo query type of the sntl_licensing_get_info API to retrieve the recipient information of the machine for which commuter authorization is required. If this attribute is not used (or NULL is provided as the value for this parameter), the commuter code will be fetched for the local machine.

NOTE This is applicable to the commute action type only.

info[out]

Pointer to the data received such as a commuter authorization string.

NOTE This is applicable to commute and return commuter action types only.

NOTE You may instead use the macros (which are wrappers to the sntl_licensing_transfer API) for setting the transfer attributes. For example, 'sntl_licensing_attr_set_transfer_units_required' is the macro for setting the license units for transfer. 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, an error code is returned indicating the reason for failure.

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