NAME

xslm_adv_request_license

SYNOPSIS

#include <libxslm.h>

xslm_uint32 xslm_adv_request_license(
    xslm_handle     session_handle,
    xslm_uuid       publisher_id,
    xslm_uint32     product_id,
    xslm_uint32     version_id,
    xslm_uint32     feature_id,
    xslm_uint32     named_user_length,
    xslm_string     * named_user,
    xslm_uint32     num_units_req,
    xslm_uint32     * num_units_granted,
    xslm_uint32     force_num_units,
    xslm_uint32     confirm_time,
    xslm_uint32     cert_auth_type
    xslm_uint32     publisher_key_length,
    xslm_bin_string * publisher_key,
    xslm_handle     * lic_handle,
    xslm_uint32     * status,
    xslm_uint32     auth_token,
    xslm_bin_string * auth_signature,
    xslm_uuid       * auth_lic_sys_id
);

DESCRIPTION

xslm_adv_request_license() asks the license server for num_units_req license units, for the product identified by publisher_id, product_id, version_id, and feature_id. This call can also provide confirm time information, via confirm_time, to the server to specify the time interval within which an xslm_confirm() call must be issued in order for the license to remain valid.

INPUT PARAMETERS

session_handle

A reference returned by xslm_adv_begin_session().

publisher_id

The software publisher identification.

product_id

The identification of the product whose license is requested.

version_id

The identification of the version of the product whose license is requested.

feature_id

The product and version’s associated feature number; if not used, must be set to 0.

named_user_length

Length of named_user in bytes. If this value is 0, no name is specified, and the licensing system should use the current system-dependent name, if required.

named_user

A text string containing the id of the named user for which a license is requested. An empty string (that is, named_user_length equal to 0) indicates that the licensing system should use the current system-dependent name, if required.

num_units_req

The number of license units requested. A value of XSLM_DEFAULT_UNITS indicates that the default number of units, as defined by the certificate data element DEFAULT_UNITS_TO_GRANT, will be requested.

force_num_units

A value of XSLM_GRANT_PARTIAL indicates that the license request may be satisfied by less than the number of units requested via the num_units_req parameter. A value of XSLM_GRANT_FULL indicates that the request may only be satisfied by at least as many units as indicated by the num_units_req parameter. No other values may be specified.

cert_auth_type

Certificate authorization request type. If this value is XSLM_CERT_AUTH_NONE, the licensing system is not required to perform any specific action to authenticate the license certificate issuer before granting a license. If this value is XSLM_CERT_AUTH_PUB_KEY, the licensing system must use the value provided via the publisher_key parameter to authenticate the license certificate issuer. If this value is XSLM_CERT_AUTH_CA, then the licensing system must perform the authentication using an authentication certificate associated with the license certificate, as described in License Certificate Authenticity.

publisher_key_len

Length of publisher_key in bytes. If this value is 0, no certificate authentication will take place, and the certificate is assumed to have been created by the application publisher.

publisher_key

Publisher-specified public key. Used to confirm the authenticity of a license certificate. The value passed must match the value of the publisher's public key contained in the license certificate.

auth_token

A 32-bit arbitrary value created by the application and used as part of the licensing system authentication process. See Process Description for more information.

INPUT/OUTPUT PARAMETERS

confirm_time

Elapsed time (in seconds) within which the license server will expect the next xslm_adv_confirm() call. This value is an integer greater than or equal to one. Failure to confirm continued license use will cause the license server to assume that the product is no longer active and, if the license is reusable, return it to the pool of available licenses.

The confirm_time value overrides any other confirmation value. If set to 0, the current value will be returned by the license.

OUTPUT PARAMETERS

num_units_granted

Number of license units granted.

lic_handle

A reference returned by this call. It is used to maintain information about the currently granted license.

status

Completion status. Detailed error code directly processable by the caller. This value is set to XSLM_STATUS_OK if no error occurred. For other messages, see ERRORS.

auth_signature

An area large enough to contain a 16-byte digital signature created by the licensing system from the input parameters and auth_token. Used as part of the licensing system authentication process.

auth_lic_sys_id

A unique identifier for the particular type of licensing system handling the current license instance. Used as part of the licensing system authentication process.

RETURN VALUE

XSLM_OK

License granted

XSLM_COMM_ERR

Communications problem

XSLM_CERT_ERR

Problem with license and/or certificate

XSLM_RESRC_UNAVL

Local resources unavailable

XSLM_PARM_ERR

Parameter error

ERRORS

The function return value gives an overall indication of the success or failure of the call. In addition, the status parameter will be set to one of the following values, to further help point to the reason for a failed request.

Note:

In the future, additional values may be defined for the status variable. An application must not rely upon these being the only possible values.

Return Value	Status Value	Explanation
XSLM_OK	XSLM_STATUS_OK	No errors occurred
	XSLM_IN_SOFT_STOP	License granted due to soft-stop policy
	XSLM_IN_RECOVERY_MODE	License granted due to disaster-recovery mode
XSLM_COMM_ERR	XSLM_LIC_SYS_NOT_RESP	The licensing system does not respond
	XSLM_NO_SVRS_FOUND	No license servers responding
XSLM_CERT_ERR	XSLM_NO_CERTIFICATES	No certificate found for the specified publisher_id, product_id, version_id and feature_id
	XSLM_CERT_NOT_STARTED	Certificate validity period not yet begun.
	XSLM_NOT_ENOUGH_CAPACITY	Capacity requested exceeds that available.
	XSLM_NOT_ENOUGH_LICS	Number of requested licenses is more than the number available.
	XSLM_NO_LICS	The number of available license units is currently less than the number needed to satisfy the request.
	XSLM_NO_MATCHING_NODE	No certificate found for current node.
	XSLM_NO_MATCHING_USERID	No certificate found for current userID.
	XSLM_INVALID_PUBLIC_KEY	Public keys do not match
XSLM_RESRC_UNAVL	XSLM_NO_RES	Platform dependent
XSLM_PARM_ERR	XSLM_BAD_PARM	One or more parameters were not correct
	XSLM_BAD_SESSION_HANDLE	The specified session handle is invalid

SEE ALSO

xslm_adv_begin_session().