Chapter 5. Industry-Standard Licensing APIs
Prev   Next

Chapter 5. Industry-Standard Licensing APIs

FLEXlm offers the most widely-used licensing API available—the FLEXlm API, which is used by over 500 software vendors worldwide. However, there has been much effort expended in the search for a “standard” licensing API.

FLEXlm offers the ISV the choice of three standard APIs:

FLEXlm is the only licensing system available which supports all three APIs.

The FLEXlm API

The FLEXlm API has evolved since 1988, with the input of most of the major software vendors in the UNIX software industry. The goal of the FLEXlm API is to give you your choice of licensing models in an easy to implement, robust package. The FLEXlm API is documented in Chapter 4, “Incorporating FLEXlm Into Your Application.”

Software License Working Group

The Software License Working Group was a sub-group of the Network Computing Forum, organized by Apollo Computer in 1988. This group published a licensing system API which Globetrotter believes to be the most usable of all the “standard” licensing APIs in existence to date. FLEXlm has supported this interface since 1990. Even though this interface is vendor-neutral and well-designed, few software companies utilize this interface, and no other “standards” organizations adopted it.

Note: You cannot mix Software License Working Group calls with either the native FLEXlm calls or the LSAPI calls.

Note: FLEXlm on Windows and Windows NT systems do not support this API.

Data types for all calls

vendor_id (char *) 


Same as vendor daemon name

vendor_key (VENDORCODE *)  


Vendor's encryption seeds

job_id (LM_HANDLE *) 


Job handle

length (int) 

Length of a string

text (char *) 

String

status (int) 

Status return from call

product_id (char *) 


Feature name

version (char *)  

Version of feature

amount (int) 

Number of licenses

queue (int) 

Enqueue request flag

check_period (int) 


check_interval

license_handle (char *) 


Handle for this license

queue_position (int) 


Our position in the queue

General Calls

ls_init (vendor_id, vendor_key, &job_id): 


Same as lc_init()

ls_terminate (job_id): 


Terminate licensing operations

ls_log_message (job_id, length, text, &status): 


Similar to lc_log()

License Brokering Calls

lb_request (job_id, product_id, version, amount, queue, check_period, &license_handle) 


Check out a license

lb_check_wait (license_handle, check_period, &queue_position) 


Check queue position for a license

lb_wait_remove (license_handle) 


Remove process from queue for this license

lb_confirm (license_handle, check_period)  


Inform daemon that license is still in use

lb_release (license_handle) 


Release a license (lc_checkin())

lb_get_cur_users (job_id, product_id, version, next, maximum_entries, queued, total_licenses, number_of_entries, entries) 


Get a list of users of “product_id” (like lc_userlist, only much harder to use).

Usage Metering Calls (Not Implemented)

um_put_record()  

um_get_record()  

um_delete_records()  

um_purge_records()  

um_undelete_records()  

LSAPI v1.1

The LSAPI interface, a licensing API first proposed in May, 1992, was designed by a consortium of software vendors with participation from several licensing system vendors. The main “claim to fame” of this interface is that it attempts to provide a solution whereby the end-user can choose the license server product from the licensing system vendor of their own choice. While the LSAPI seems to be a simple API, it hides the fact that your code will increase in complexity in order to solve the problem of the replaceable license server, (since both the license server and the licensing system library are, in theory, replaceable by the end-user, any security must be built into your code, independent of the license server). The complexity is exposed to you in the “challenge mechanism”, which is a standard encryption technique known as “handshaking”.

Note: If you are considering using LSAPI in your product, you should read U.S. patent #5,375,206 issued to HP, and understand its implications.

LSAPI has several significant drawbacks compared to the FLEXlm API. In addition, Globetrotter believes that the stated goal of license server independence cannot be met by the current version of the LSAPI spec (see last point below). Some of the drawbacks of LSAPI compared to the native FLEXlm API are:

  • Unreasonable error reporting (only a total of 14 error codes.)

  • No ability for the vendor to support license queueing.

  • No vendor-specific checkout filtering.

  • New hostid types are not definable by the software vendor.

  • No provision to pass messages between the client and license server.

  • No way to get license status without doing I/O to the license server.

  • No way to support a node-locked license without a license server.

  • No way to retrieve information about the licensing policy.

  • No way to ship a vendor-neutral license. This means that, in order to accomplish the stated goal of allowing your end-user to select the licensing system from the vendor of their choice, YOU would have to provide licenses in the format required by EACH AND EVERY license system which your customer might want to choose. In practice, what this means is that you would need to build and test with every possible licensing system.

Note: You cannot mix LSAPI calls with either the native FLEXlm calls or the Software License Working Group calls.

Data types for all calls

LS_ULONG  

unsigned long

LS_STATUS_CODE 


unsigned long

LS_STR 

char

LS_CHALLENGE 


 structure

LS_CHALLENGE_FLEXLM 


 structure

LS_HANDLE 

unsigned long

LS_VOID 

void

LSAPI General Calls

List providers of licensing service

LS_STATUS_CODE LSEnumProviders (LS_ULONG Index, LS_STR *Buffer) 

Get message text from licensing system

LS_STATUS_CODE LSGetMessage(LS_HANDLE Handle, LS_STATUS_CODE Value, LS_STR *Buffer, LS_ULONG BufferSize)  

Query License information

LS_STATUS_CODE LSQuery(LS_HANDLE Handle, LS_ULONG Information, LS_VOID *InfoBuffer, LS_ULONG BufferSize, LS_ULONG *ActualBufferSize)  

Release license

LS_STATUS_CODE LSRelease(LS_HANDLE Handle, LS_ULONG TotUnitsConsumed, LS_STR *LogComment)  

Request license

LS_STATUS_CODE LSRequest(LS_STR *LicenseSystem, LS_STR *PublisherName, LS_STR *ProductName, LS_STR *Version, LS_ULONG TotUnitsReserved, LS_STR *LogComment, LS_CHALLENGE *Challenge, LS_ULONG *TotUnitsGranted, LS_HANDLE *Handle) 

Note: The challenge in your first LSRequest() call must be of type LS_CHALLENGE_FLEXLM, which is a FLEXlm vendor specific challenge mechanism. Challenge should be setup as in the following code example before calling LSRequest(): 

LS_CHALLENGE_FLEXLM *Challenge;
LM_CODE(vendor_code, ENCRYPTION_CODE_1, ENCRYPTION_CODE_2, VENDOR_KEY1,
		VENDOR_KEY2, VENDOR_KEY3, VENDOR_KEY4, VENDOR_KEY5);
...
Challenge->Protocol = LS_FLEXLM_PROTOCOL;
strcpy( Challenge->ChallengeData.VendorName, VENDOR_NAME);
Challenge->ChallengeData.VendorCode = vendor_code;
Challenge->Size = sizeof(*Challenge);
...
LSRequest( ...., (LS_CHALLENGE *)Challenge, ...);

Update license status

LS_STATUS_CODE LSUpdate(LS_HANDLE Handle, LS_ULONG TotUnitsConsumed, LS_ULONG TotUnitsReserved, LS_STR *LogComment, LS_CHALLENGE *lpChallenge, LS_ULONG *TotUnitsGranted) 

For more details on the LSAPI interface, see the “License Service Application Programming Interface, API Specification v1.1,” or contact Microsoft via e-mail at “lsapi@microsoft.com”, or Dave Berry, Microsoft Developer Relations, 1 Microsoft Way, 4/2, Redmond, WA 98052-6399.

Remember, you cannot mix LSAPI and native FLEXlm calls in a single application. The license servers can support a mix of applications which use either native FLEXlm or LSAPI, but a single executable must use either native FLEXlm or LSAPI.

Prev Table of Contents Next
Chapter 4. Incorporating FLEXlm Into Your Application  Chapter 6. Controlling Licensing Behavior Of Your Application With lc_set_attr