NAME

xslm_get_log_data

SYNOPSIS

#include <libxslm.h>

xslm_uint32 xslm_get_log_data(
    xslm_uuid       server_id,
    xslm_uint32     tod_type,
    xslm_tod        log_start,
    xslm_tod        log_end,
    xslm_uint32     log_class,
    xslm_uint32     log_record_type,
    xslm_uint32     log_record_subtype,
    xslm_handle     * query_handle,
    xslm_uint32     log_buffer_length,
    xslm_bin_string * log_buffer,
    xslm_uint32     * status,
    xslm_uint32     auth_token,
    xslm_bin_string * auth_signature,
    xslm_uuid       * auth_lic_sys_id
);

DESCRIPTION

xslm_get_log_data() requests the license server to return all the log records which match the input parameters.

INPUT PARAMETERS

server_id

Identification of server to which this request is being directed.

tod_type

Indicates whether the time/date values on log_start and log_end refer to server or application-client local time. A value of XSLM_LOGTOD_SERVER indicates server time; a value of XSLM_LOGTOD_APPL indicates application client time.

log_start

The earliest date for which log records are to be retrieved.

log_end

The last date for which log records are to be retrieved.

log_class

The class ID (XSLM_LOGCLASS_ADMIN, XSLM_LOGCLASS_APPL, or XSLM_LOGCLASS_SYSTEM) of the log records to be retrieved. Use XSLM_LOGCLASS_ANY to retrieve log records of any class.

log_record_type

The value of the type data element of the log records to be retrieved. Use XSLM_LOGTYPE_ANY to retrieve log records for any event type. If XSLM_LOGCLASS_ANY is specified for the log record class ID, then XSLM_LOGTYPE_ANY must be specified for this parameter.

log_record_subtype

The value of the subtype data element of the log records to be retrieved. Use XSLM_LOGSUBTYPE_ANY to retrieve log records for any event subtype. If XSLM_LOGTYPE_ANY is specified for the log record type, then XSLM_LOGSUBTYPE_ANY must be specified for this parameter.

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

log_buffer_length

As an input parameter, the length of the buffer to receive the results of the query. As an output parameter, the length of data returned.

The buffer must be large enough to contain the longest record to be returned. If a record does not fit within the specified buffer size, then a return code of XSLM_PARM_ERR and a status code of XSLM_BAD_BUFFER_LENGTH is returned, and log_buffer_length is set to the size required to hold the record.

query_handle

This parameter allows the caller to use a buffer smaller than that required to hold all the results from the query. On the first query, a value of zero must be passed to indicate that this is the first call for this query. If a value of zero is returned on output, all the query results were placed in the key buffer. A non-zero value indicates that the buffer was too small and this value must be used as the input query_handle value to obtain the next part of the query results.

In order to receive all the results of the query, the caller must continue to call xslm_get_log_data(), passing the last returned query_handle value until a value of zero is finally returned. Note that the results of the query may not be internally consistent, because changes can occur between calls, whenever multiple calls are required to obtain all the results from a single query.

OUTPUT PARAMETERS

log_buffer

Buffer into which the log records are returned. Each log record is returned as a set of data elements, and the log record itself is identified by a data element. Log records are returned in random order. A server may return more than one log record at the same time, if they all fit within the buffer. See for a list of all 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_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_PARM	One or more parameters were not correct
	XSLM_INVALID_TOKEN	query_handle contains a value which is not currently valid
	XSLM_BAD_BUFFER_LENGTH	The length of the buffer is too small to hold at least one complete record
	XSLM_BAD_SERVER_ID	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 LOGGED_EVENT data elements (see Data Elements for details), each containing data about one logged event.

SEE ALSO

None.