NAME

xslm_adv_query

SYNOPSIS

#include <libxslm.h>

xslm_uint32 xslm_adv_query(
    xslm_handle     session_handle,
    xslm_handle     lic_handle,
    xslm_uint32     query_type,
    xslm_uint32     * query_buffer_length,
    xslm_bin_string * query_buffer,
    xslm_uint32     * status,
    xslm_uint32     auth_token,
    xslm_bin_string * auth_signature,
    xslm_uuid       * auth_lic_sys_id
);

DESCRIPTION

xslm_adv_query() returns various types of license certificate information associated with the specified license handle.

INPUT PARAMETERS

session_handle

A reference returned by xslm_adv_begin_session().

lic_handle

A reference returned by xslm_adv_request_license().

query_type

Value which identifies the information to be returned:

Query Type	Explanation
XSLM_QUERY_PUBLISHER_INFO	Return the publisher-unique section of the license certificate publisher defined data element structure. A returned query_buffer_length value of null indicates that the certificate contains no publisher-unique section.
XSLM_QUERY_CUST_DEF_INFO	Return application-related information specified by the customer. A returned query_buffer_length value of null indicates that the certificate does not contain the CUSTOMER_ASSIGNED_APPL_INFO data element.
XSLM_QUERY_CERTIFICATE	Return the certificate as it has been created by the application publisher.
XSLM_QUERY_CERT_RELATED_INFO	Return the certificate related information maintained by the Licensing System.

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

query_buffer_length

As an input parameter, the length of the buffer to receive the results of the query. A value of zero indicates a request for the size of the buffer required to contain the entire 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 data returned, 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 result of the query. If it is not, no data is placed in the buffer and the output value of query_buffer_length contains the buffer length needed to contain the entire result. A value of zero on output indicates that the requested information was not available on the certificate.

Note that because the certificate related information may change at any time, the actual size needed may be different from the returned value in cases other than XSLM_QUERY_PUBLISHER_INFO and XSLM_QUERY_CERTIFICATE query types.

OUTPUT PARAMETERS

query_buffer

Buffer in which the query results are returned. The results are returned as a set of one or more data elements.

status

Completion status. Detailed error code directly addressable 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

Query completed successfully

XSLM_COMM_ERR

Communications problem

XSLM_RESRC_UNAVL

Resources unavailable

XSLM_PARM_ERR

Bad parameters passed

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_COMM_ERR	XSLM_COMM_UNAVAIL	Communications problem
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 certificate being retrieved.
	XSLM_BAD_LICENSE_HANDLE	Invalid license handle passed.
	XSLM_BAD_PARM	One or more parameters were not correct
	XSLM_BAD_SESSION_HANDLE	The specified session handle is invalid
	XSLM_INVALID_API_USE	Attempt to combine standard and advanced API for the same handle

OUTPUT DATA

• For XSLM_QUERY_PUBLISHER_INFO, the data element PUBLISHER_SECTION, if present, followed by the data element PUBLISHER_USE, if present.

• For XSLM_QUERY_CUST_DEF_INFO, the data element CUSTOMER_ASSIGNED_APPL_INFO, if present.

• For XSLM_QUERY_CERTIFICATE, the data element CERTIFICATE.

• For XSLM_QUERY_CERT_RELATED_INFO, the data element CERTIFICATE_RELATED_INFORMATION.

See Data Elements for details on the data elements.

Note that if the query_buffer_length parameter does not specify a large enough buffer to contain the entire query result, no data is returned

SEE ALSO

xslm_adv_begin_session(), xslm_adv_request_license().