|
SLSAPI Data Types
typedef DWORD SLS_HANDLE; 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; } SLS_DATE; The SLS_DATE defines a date structure that contains calendar year, month and day. It is part of the SLS_LICENCE structure. Licence 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 } SLS_LICENCE; The SLS_LICENCE defines Sheriff's licence policy structure. It is used by SLS_License to issue licence programmatically. Type Specifies the type of the licence policy. It can be a combination of the following values: //type of licence Meter 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.EndDate Used only for expiry date licensing, i.e. when type is SLS_TYPE_EXPIRATION, to specify the expiration date.CoUsers Specifies the maximum concurrent users. Maximum value is 99999. AccessKey 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. Request typedef struct _SLS_REQUEST 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; } SLS_PERMIT; 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. UnitsGranted Returns the total number of units granted and reserved. AccessKey Returns the publisher-defined feature access key. Update typedef struct _SLS_UPDATE UnitsReserved 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. UnitsConsumed 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.Release
typedef struct_SLS_RELEASE UnitsConsumed Specifies the total number of units consumed since the initial call to the SLS_Request function. Licence Info typedef struct _SLS_LICENCE_INFO Type, Meter, EndDate, CoUsers, AccessKey as explained in SLS_LICENCE. State Returns the state of the licence being requested. Its value can be one of the following: #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 MeterUsage Specifies the total number of units or days that have been used since the licence was purchased. StartDate Specifies the purchase date of the licence policy. ActiveUsers 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]; } SLS_PRODUCT_INFO; The SLS_PRODUCT_INFO structure is used by SLS_QueryProductInfo to retrieve the product information including ProductID, Product Name and its Licence Path. Challenge typedef struct _SLS_CHALLENGE Protocol 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. Size Specifies the size, in bytes, of the ChallengeData (SLS_CHALLDATA) structure. ChallengeData Structure that contains the challenge that the application passes to the licence system and the response the licence system returns to the application. Remarks 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 SecretIndex Specifies the index of the secret value to be challenged. The secret index is 1-based. Random Specifies a random 32-bit value. MsgDigest Structure that contains the message digest that is computed by the MD5 Message-Digest Algorithm from RSA Data Security, Inc. Remarks 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) ) where:
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 MessageDigest[16] Specifies a 128-bit message digest that is the output of the MD5 Message-Digest Algorithm. Licence Options typedef struct _SLS_OPTIONS 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. HeartbeatTime 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. ReclaimTime 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 The SLS_USER_INFO structure is used by SLS_QueryUserInfo to retrieve user's information UserName The name of the user as provided when call SLS_Request or SLS_RequestEx UserID The ID of the user as provided when call SLS_RequestEx LoginTime The time when SLS_Request or SLS_RequestEx is called. LastUpdateTime The time the last SLS_Update is called. |