EasyLicenser Extended API For C/C++ README
==========================================

Introduction
------------

The EasyLicenser extended API For C/C++ is an extension to
the core EasyLicenser C/C++ runtime library and is
included with the EasyLicenser 2.5 multiplatform
C/C++ runtime library package.

The API provides a higher level API that simplifies
application integration by providing the basic
and functionally complete primitives "activate", 
"check" and "deactivate". The API also implements 
the notion of deferred node locking and deferred
time limited licensing when an appropriate 
auxiliary license key issued by Agilis is provided
to the activation API call in addition to the
vendor license key.

Packaging
---------

The following files are specific to the extended-API
functionality:

1. cpp/demo/src/cdemoextapi.c, 
   cpp/demo/bin/<<platform>>/cdemoextapi[.exe]
   Source and binary code for a demo application illustrating 
   how to use the extended API.
2. cpp/include/ezLicenseExtAPI.h:
   Self-documenting header file exporting the extended API.

Impact of extended API and deferred licensing
---------------------------------------------

Using the extended API has the following impact:
(a) Vendor key generation:
    No impact.  The existing key structure can continue
    to be used including custom keys, custom cookies,
    options, etc.
    Optionally, the following EasyLicenser system product
    options may be defined:
    1. EZLM:KEY-EXPIRE-DAYS: this is a numerical value
       representing the relative expiration days from
       the date of activation, if required to be different
       from the day limit that is programmed into the
       Agilis-supplied key.  If the value exceeds the
       Agilis-supplied limit, it is truncated to the latter.
    2. EZLM:KEY-SHELF-LIFE-HRS: this is a numerical value
       representing the shelf life of a key in hours, which
       is the amount of time within which the end user must
       activate the key from the time of its creation by
       the vendor.  It is useful for reducing exposure to
       multiple uses of a deferred-node-locked key that is
       usually not a time limited trial license.
    Neither option has any effect unless the vendor key
    is accompanied by an enabling Agilis key.  Further,
    if neither option is specified, for example in a 
    conventional node-locked perpetual license, the
    accompanying enabling key, if any, is ignored.
(b) Vendor key distribution:
    If deferred licensing is to be used, the vendor must also
    distribute a special time-limited "N-day trial generator" 
    license key issued by Agilis to the vendor specifically 
    for the associated product.  The vendor must ensure that
    the key is present when using deferred licensing for
    time limited trials.  This is in addition to the key
    normally provided by the vendor.  The vendor must also
    ensure that when a trial license is converted into
    production, the trial-generator key is ignored.
(c) Application integration:
    The extended API's replace the core API's, requiring
    source code changes that mostly represent a simplification
    in the integration code.  Therefore development effort
    accompanied by a new product release are required.
(d) Application packaging:
    The existing ezLicenserlib20.dll/so and its associated signature
    if any are replaced with the updated ezLicenserlib20.dll/so and
    its associated signature.  No path environment variable changes 
    are required.

Getting started on application integration with the extended API
----------------------------------------------------------------

1. Use this README for instructions on how to compose your keys,
   and what enabling keys to get from Agilis if utilizing the
   deferred-node-locked and deferred-time-limited functionality.
2. Use the demo application as a head start for an actual 
   implementation.  View the comments in the application for
   guidelines on how to head start your own application based on
   the demo code.
3. Use the documentation in ezLicenseExtAPI.h for guidelines on
   how to use the extended API calls.

Deploying the application with a trial license
----------------------------------------------
Obtain the 1-year time-limited 30-day trial generator 
key from Agilis and include it in your trial license
product packaging.  You will need to obtain a new key
from Agilis at the end of the 1-year period of validity.

License key deployment for applications having visible activation
-----------------------------------------------------------------
When the application provides an installer or other activation
mechanism for prompting the user to enter a license key (whether
trial or perpetual), the activation sequence invokes the extended
API to deactivate an existing installation and then perform an
activation with the newly supplied key, for example a perpetual key
representing a replacement for a trial key.  The enabling key
parameter is ignored in this second activation call if the 
replacement key is perpetual.

Hot license key deployment for applications lacking visible activation
----------------------------------------------------------------------
When a user interface is not available for explicitly controlling
activation (for example a self-configuring server application), 
and the process of upgrading a license key consists of
replacing an existing key with a new key, the above deployment logic
is modified to occur on the fly as follows:
at the time a license check would ordinarily be made during normal
execution of the application, the license check is preceded by a
"new key" check by comparing the relative timestamps of the license
key and the key cookie.  For example, if the key and cookie are saved
in files, code similar to the following may be used:
        #include <sys/stat.h>
        :
	time_t currTs = 0;
	time(&currTs);
	struct stat statbufold;
        struct stat statbufnew;
	if (stat(cookiefile, &statbufold) < 0)
		return -1;
	if (stat(newkeyfile, &statbufnew) < 0)
		return -1;
	if (statbufnew.st_mtime > 
	    statbufold.st_mtime) {
           /* proceed with new-key deployment */
        }

If the cookie is maintained in the registry then the registry
should also save the date of installation.


                            -x-
Revision History
----------------
04/27/07 Creation for EasyLicenser 2.5 C/C++ runtime packaging.
03/09/05 Creation for C/C++ extended API
