NAME

xslm_get_license_instances

SYNOPSIS

#include <libxslm.h>

xslm_uint32 xslm_get_license_instances(
    xslm_uuid       server_id,
    xslm_uuid       publisher_id,
    xslm_uint32     product_id,
    xslm_uint32     version_id,
    xslm_uint32     feature_id,
    xslm_uint32     * instance_buffer_length,
    xslm_bin_string * instance_buffer,
    xslm_uint32     * status,
    xslm_uint32     auth_token,
    xslm_bin_string * auth_signature,
    xslm_uuid       * auth_lic_sys_id
);

DESCRIPTION

xslm_get_license_instances() asks the license server to return the complete set of license instance records which match the specified key fields. When all of the input key parameters have values of zero, the server returns all valid license instance records.

INPUT PARAMETERS

server_id

Identification of server to which this request is being directed.

publisher_id

The software publisher identification for all license instance records to be returned. It uniquely identifies the publisher. A value of zero indicates that instance records for all publishers within the specified server_id are to be returned. Whenever a value of zero is used for this parameter, the product_id, version_id, and feature_id parameters must all also have values of zero.

product_id

ID number of the product for which all license instance records are to be returned. A value of zero indicates that all the instance records, which match the server_id and publisher_id are to be returned. Note that whenever a value of zero is used for this parameter, the version_id and feature_id parameters must all also have values of zero.

version_id

The version of the product for which all license instance records are to be returned. A value of zero indicates that all the instance records, which match the server_id, publisher_id, and product_id, are to be returned. Note that whenever a value of zero is used for this parameter, the feature_id parameter must also have a value of zero.

feature_id

The associated feature number of the product for which all license instance records are to be returned. A value of zero indicates that all the instance records, which match the server_id, publisher_id, product_id, and version_id, are to be returned.

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

instance_buffer_length

As an input parameter, the length of the buffer to receive the results of the query. A value of zero on input indicates a request for the size of the buffer required to contain the all the results of the query. No data is returned in the key buffer when a value of zero is passed. As an output parameter the length of usable data returned in the key buffer or the size of the buffer required to contain the entire query result if the input value was zero.

Note that the buffer must be large enough to contain the entire license instances data area. If it is not, no data is placed in the buffer and the output value of this parameter contains the size of the buffer length needed to contain the entire result. Note also that because the license instances data may change at any time, the actual size needed may be different from the returned value.

OUTPUT PARAMETERS

instance_buffer

Pointer to the buffer into which the query results are returned.

status

Completion status. Detailed error code directly addressable by the caller. This value is set of XSLM_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

Query completed successfully

XSLM_COMM_ERR

Communications problem

XSLM_CERT_ERR

Problems with the license and/or certificate

XSLM_RESRC_UNAVL

Resources unavailable

XSLM_PARM_ERR

Bad parameters passed

XLSM_AUTH_ERROR

Requester is not authorized

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_PARTIAL_DATA	Invalid license instance record(s) encountered. Only valid instance records returned.
XSLM_COMM_ERR	XSLM_COMM_UNAVAIL	Communications problem
XSLM_CERT_ERR	XSLM_NO_CERTIFICATES	No certificates matched the query.
XSLM_RESRC_UNAVL	XSLM_NO_RES	Local platform specific environmental problems
	XSLM_SERVER_ERROR	Unrecoverable environmental error was encountered by the license server
XSLM_PARM_ERR	XSLM_BAD_BUFFER_LENGTH	The non-zero value for the buffer length was too small for the data being retrieved
	XSLM_BAD_PARM	One or more parameters were not correct
	XSLM_BAD_SERVER_ID	The server_id specified does not correspond to a known server
XSLM_AUTH_ERROR	XSLM_NOT_AUTHORIZED	The requester is not authorized to perform the requested action

OUTPUT DATA

A sequence of 1 or more LICENSE_INSTANCES_INFORMATION data elements (see Data Elements for details), unless the output buffer is not large enough to contain all data elements matching the query in which case no data is returned.

SEE ALSO

xslm_release_license_instance().