Contents - Index SlsAPI Data Types & Structures

SLSAPI Data Types


Defines the handle to the licensing context used by the licence service function calls.

SLSAPI Data Structures

Licence Date

typedef struct _SLS_DATE

     DWORD Year,
     DWORD Month,
     DWORD Day;

The SLS_DATE defines a date structure that contains calendar year, month and day. It is part of the SLS_LICENCE structure.


typedef struct _SLS_LICENCE
     DWORD Type; //type of licence
     DWORD Meter; //for metering, e.g. Unit, Time metering
     SLS_DATE EndDate; //for expiration date
     DWORD CoUsers; //Concurrent users
     DWORD AccessKey; //Access control key

The SLS_LICENCE defines Sheriff's licence policy structure. It is used by SLS_License to issue licence programmatically.


Specifies the type of the licence policy. It can be a combination of the following values:

//type of licence
#define SLS_TYPE_UNDEFINED 0x0000 //Undefined
#define SLS_TYPE_UNIT_METER 0x0001 //Unit Metering
#define SLS_TYPE_TIME_METER 0x0002 //Time Metering
#define SLS_TYPE_EXPIRATION 0x0004 //Expiry Control
#define SLS_TYPE_CONCURRENCY 0x0008 //Concurrency Control

#define SLS_TYPE_REUSABLE_KEY 0x0100 //Reusable key
#define SLS_TYPE_REUSABLE_REF 0x0200 //Reusable reference
#define SLS_TYPE_UNEXPORTABLE 0x0400 //Export Disabled
#define SLS_TYPE_STANALONE 0x0800 //Standalone


Used only for metering, i.e when type is either SLS_TYPE_UNIT_METER or SLS_TYPE_TIME_METER, to specify the total amount of units or total number of days allowed in the licence policy. Maximum value is 99999.


Used only for expiry date licensing, i.e. when type is SLS_TYPE_EXPIRATION, to specify the expiration date.


Specifies the maximum concurrent users. Maximum value is 99999.


Specifies a key to access application features. A software application can offer many features and these features can be managed in many levels. The software publisher may want to license the software in levels. The AccessKey is used by software publishers to control the accessibility of features. The AccessKey is defined by software publishers and its meaning is also only interpreted by the publishers. Maximum value is 99999.


typedef struct _SLS_REQUEST
     DWORD UnitsReserved;

The SLS_REQUEST is used for requesting a licence to run the application. It is used by SLS_Request. When the licensing policy requires unit metering, the data member UnitsReserved specifies the number of units to run the application; when the licensing policy does not requires unit metering, the UnitsReserved should be set to zero.

typedef struct _SLS_PERMIT
     DWORD UnitsGranted;
     DWORD AccessKey;

The SLS_PERMIT is used for receiving a licensing permit, when SLS_Request is called to request a licence to run the application, or when SLS_Update is called to update the licence status.


Returns the total number of units granted and reserved.


Returns the publisher-defined feature access key.


typedef struct _SLS_UPDATE
     DWORD UnitsReserved;
     DWORD UnitsConsumed;

The SLS_UPDATE is used for updating licence status. It is used by SLS_Update.


Specifies the total number of units to be reserved. If no additional units are required since the initial call to the SLS_Request function or the last call to the SLS_Update function, then this parameter should be the current total returned in the SLS_PERMIT.UnitsGranted parameter. The total reserved includes the units consumed. That is, if an application requests 100 units, and then consumes 20 units, there are still 100 units reserved but only 80 available for consumption.

If additional units are required, the application must calculate a new total for UnitsReserved.

The licence system verifies that the requested number of units exist, and it may reserve those units, but these units are not consumed at this time.

This value may be smaller than the original number requested by SLS_Request to indicate that fewer units are needed than originally anticipated.


Specifies the total number of units consumed since the initial call to the SLS_Request function. If the UnitsConsumed exceeds the number of units reserved, the error SLS_E_UNIT_EXCEEDED is returned and the remaining units are consumed.


typedef struct_SLS_RELEASE
     DWORD UnitsConsumed;

The SLS_RELEASE is used by SLS_Release to report licence usage.


Specifies the total number of units consumed since the initial call to the SLS_Request function.

Licence Info

typedef struct _SLS_LICENCE_INFO
     //Licence Part
     DWORD Type; //type of licence
     DWORD Meter; //Units or Days limit
     SLS_DATE EndDate; //Expiration date
     DWORD CoUsers; //Concurrent users
     DWORD AccessKey; //Access control key
     //Usage Part
     DWORD State; //State of licence
     DWORD MeterUsage; //Units used, days used
     SLS_DATE StartDate; //Start date
     DWORD ActiveUsers; //Number of active users

The SLS_LICENCE_INFO structure is used by SLS_QueryLicenceInfo to retrieve the licence policy and its current usage.

Type, Meter, EndDate, CoUsers, AccessKey as explained in SLS_LICENCE.


Returns the state of the licence being requested. Its value can be one of the following:

#define SLS_STATE_UNDEFINED 0x0000 //Licence is undefined
#define SLS_STATE_BAD 0x0001 //Licence is invalid
#define SLS_STATE_EXPIRED 0x0002 //Licence has expired
#define SLS_STATE_EXHAUSTED 0x0003 //Licence units have run out
#define SLS_STATE_OK 0x0008 //Licence is valid


Specifies the total number of units or days that have been used since the licence was purchased.


Specifies the purchase date of the licence policy.


Specifies the number of active users at the time this information is being requested.

Product Info

typedef struct _SLS_PRODUCT_INFO
     char ProductID[32];
     TCHAR ProductName[128];
     TCHAR LicencePath[MAX_PATH];

The SLS_PRODUCT_INFO structure is used by SLS_QueryProductInfo to retrieve the product information including ProductID, Product Name and its Licence Path.


typedef struct _SLS_CHALLENGE
     DWORD Protocol;
     DWORD Size;
     SLS_CHALLDATA ChallengeData;

The SLS_CHALLENGE structure is used for both the challenge and the response of the SLS_License, SLS_Request and SLS_Update licence service functions. It is the main structure in the challenge/response mechanism, and it is supported by all challenge/response protocols.


Specifies the protocol setting for licence authentication. Currently only the basic protocol SLS_BASIC_PROTOCOL is supported. If challenge is not desired, Protocol should be set to SLS_NO_PROTOCOL.


Specifies the size, in bytes, of the ChallengeData (SLS_CHALLDATA) structure.


Structure that contains the challenge that the application passes to the licence system and the response the licence system returns to the application.


Use the SLS_CHALLDATA structure to pass the challenge to the licence system. The licence system also returns the challenge response in the SLS_CHALLDATA structure.

Because the SLS_CHALLDATA structure can vary depending on the protocol specified in the Protocol member, this structure must be a single contiguous entity in memory and must not exceed the number of bytes specified in the Size member. It cannot contain any pointers.

SLSAPI passes the Protocol, the Size of the SLS_CHALLDATA structure, and the actual data contained in the structure to the licence system. The licence system, in turn, casts the byte sequence into the appropriate structure based on the Protocol specified.

The constant value SLS_BASIC_PROTOCOL specifies a standard basic challenge protocol that is supported by all SLSAPI. When the Protocol specified is SLS_NO_PROTOCOL, there is no challenge and no response.

Challenge Data

typedef struct _SLS_CHALLDATA
     DWORD SecretIndex;
     DWORD Random;
     SLS_MSG_DIGEST MsgDigest;

The SLS_CHALLDATA structure is passed in the SLS_CHALLENGE structure. The SLS_CHALLDATA structure passes the challenge from the application to the licence system, and passes the response from the licence system back to the application.


Specifies the index of the secret value to be challenged. The secret index is 1-based.


Specifies a random 32-bit value.


Structure that contains the message digest that is computed by the MD5 Message-Digest Algorithm from RSA Data Security, Inc.


In the basic challenge protocol, the application must choose the index of the secret to be challenged and it must generate a random number. It must then compute a message digest using the MD5 Message-Digest Algorithm. The input to the algorithm is formed by concatenating the input parameters to the function being called, the random number, the index of the secret to be challenged, and the actual secret value. The input parameters are described in the SLSAPI functions. The application then passes the algorithm output to the licence system.

The licence system authenticates the message digest and computes a new message digest consisting of the output parameters, a new random number, a new index of the secret to be challenged, the actual secret value and the returned status. This new message digest is passed back to the application, which, in turn, authenticates it. Note that the actual secret value never passes between the application and the licence system in plain text.

If the function h(x) is the algorithm that, given input x, returns the output of the MD5 Message-Digest Algorithm, then the following briefly illustrates the basic protocol.

The application passes the SLS_MSG_DIGEST structure to the licence system:

h(in + Rin + Xin + S (X) )

The licence system passes a new SLS_MSG_DIGEST to the application:

h(out + Rout + Xout + S (X) )


  • in is a byte stream that encodes the input parameters
  • Rin is the random number generated by the application
  • Xin is the index of the secret to be challenged chosen by the application
  • S indicates a secret
  • S (X) is the actual secret value
  • + denotes concatenation.


  • out is a byte stream that encodes the output parameters
  • Rout is the random number generated by the licence system
  • Xout is the index of the secret to be challenged chosen by the licence system

This data format can be invalid if the Protocol specified in the SLS_CHALLENGE structure is not SLS_BASIC_PROTOCOL. Other protocols may define their own SLS_CHALLDATA format. Particularly if the Protocol is specified as SLS_NO_PROTOCOL then there will be challenge implemented between the application and the licence system.

Message Digest

typedef struct _SLS_MSG_DIGEST
     char MessageDigest[16]; //binary data

The SLS_MSG_DIGEST structure is passed in the SLS_CHALLDATA structure. The MD5 Message-Digest Algorithm from RSA Data Security, Inc., computes the SLS_MSG_DIGEST structure by using the following elements as input: the input and output parameters to the LSRequest or LSUpdate licence service functions; a random number; the index of an application secret; and the actual application secret.


Specifies a 128-bit message digest that is the output of the MD5 Message-Digest Algorithm.

Licence Options

typedef struct _SLS_OPTIONS
     DWORD HeartbeatTime; //heartbeat time
     DWORD ReclaimTime; //reclaim time
     DWORD Reserved1; //reserved, should be set to 0
     DWORD Reserved2; //reserved, should be set to 0

The SLS_OPTIONS structure is used by SLS_SetOptions to set various licence options at run time. There are two options supported in the current version, MinReclaimTime and MaxReclaimTime.


If the user has not updated its licence status within the time specified by HeartbeatTime, then Sheriff decides that the user has become inactive and its licence is ready to be reclaimed.


If the user has not updated its licence status within the time specified by MaxReclaimTime, then Sheriff decides that the user has become inaccessible and its licence will be reclaimed immediately.

User Info

typedef struct _SLS_USER_INFO
     char UserName[32];
     DWORD UserID;
     SLS_DATE_TIME LoginTime;
     SLS_DATE_TIME LastUpdateTime;

The SLS_USER_INFO structure is used by SLS_QueryUserInfo to retrieve user's information


The name of the user as provided when call SLS_Request or SLS_RequestEx


The ID of the user as provided when call SLS_RequestEx


The time when SLS_Request or SLS_RequestEx is called.


The time the last SLS_Update is called.