C-Interface

the c interface of licensespring's c++ sdk allows using sdk features in c applications this tutorial will explain how to implement licensing in a c application using the licensespring sdk in this article we will look at activating, checking, and deactivating licenses this functionality can be implemented using the lslicensehandler struct it is a wrapper of c++ licensehandler class and is similar in use sdk configuration to initialize the sdk you will need to fill in your application name and version, product code and either api and shared key, or oauth client id and client secret oauth support was added in v7 35 0 of the sdk see oauth authorization docid\ xhyzaual9qy4jerxkilmk on how to set up oauth see the c++ sdk configuration and usage docid\ mtxgbtqymb doqfxbcqop on how to retreive credentials when you have the necessary values, create the lsconfiguration object const char appname = "my licensespring application"; const char appversion = "1 0 0"; // use in case of standard authentication const char apikey = "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx"; const char sharedkey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // use in case of oauth authentication std string clientid = "xxxxxx xxxxx yyy"; std string clientsecret = "ssssssssssssssssssssssssssssss"; const char productcode = "xx"; lsextendedoptions options = createlsextendedoptions(); lsconfiguration configuration = createlsconfiguration(apikey, sharedkey, productcode, appname, appversion, options); freelsextendedoptions(options); // or // options >setcryptoproviderkey(options, "password for license encryption key generation"); // lsconfiguration configuration = createlsconfigurationoauth(apikey, sharedkey, productcode, appname, appversion, options); // freelsextendedoptions(options); you have to create a lsextendedoptions object even if you don’t intend to change its values it is necessary to copy the default values to the lsconfiguration then you can delete the options object now you can create and initialize lslicensehandler using this configuration lslicensehandler lh = createlslicensehandler(configuration); license activation to activate a license, you need its key or user email and password for information about getting license keys see c++ sdk configuration and usage docid\ mtxgbtqymb doqfxbcqop for information about user based licenses see user based licensing docid\ xepx04m3oh f6s8ylf6mz using these values, create a lslicenseid and call activation method lslicenseid licenseid = createlicenseidfromkey("xxxx xxxx xxxx xxxx"); lh >activatelicense(lh, licenseid); local license make sure that you check if a license exists on the device before a new activation for more information see c++ sdk configuration and usage docid\ mtxgbtqymb doqfxbcqop if(!lh >islicenseexists(lh)) //activate a new license license check it is recommended to perform a local license check at application start to confirm that the local license file belongs to the current device, has not been tampered with and is still valid online license check refreshes the local license with the data from licensespring backend // local check // setting verifysignature to true does a signature verification which // fails if the license file was tampered with bool verifysignature = true; lh >checklicenselocal(lh, verifysignature); // online check lsinstallationfile pinstallfile = lh >checklicense( lh ); if( pinstallfile ) freelsinstallationfile( pinstallfile ); this method also returns the most recent lsinstallationfile available for the license which can be useful for managing software updates \[todo insert link to the article about handling versions] you can also check for active, valid, enabled, and expired licenses using islicenseactive , islicensevalid , islicenseenabled , and islicenseexpired methods respectively full code sample below you can find a code sample that initializes the sdk, retrieves a local license or activates a new one, and performs the necessary checks const char appname = "my licensespring application"; const char appversion = "1 0 0"; // use in case of standard authentication const char apikey = "xxxxxxxx xxxx xxxx xxxx xxxxxxxxxxxx"; const char sharedkey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; // use in case of oauth authentication std string clientid = "xxxxxx xxxxx yyy"; std string clientsecret = "ssssssssssssssssssssssssssssss"; const char productcode = "xx"; lsextendedoptions options = createlsextendedoptions(); lsconfiguration configuration = createlsconfiguration(apikey, sharedkey, productcode, appname, appversion, options); freelsextendedoptions(options); // or // options >setcryptoproviderkey(options, "password for license encryption key generation"); // lsconfiguration configuration = createlsconfigurationoauth(apikey, sharedkey, productcode, appname, appversion, options); // freelsextendedoptions(options); lslicensehandler lh = createlslicensehandler(configuration); if(!lh >islicenseexists(lh)) { lslicenseid licenseid = createlicenseidfromkey("xxxx xxxx xxxx xxxx"); lh >activatelicense(lh, licenseid); if(lh >waserror(lh)) { const char error = lh >getlasterrormsg(lh); enum lserrorcode code = lh >getlasterror(lh); printf("error occurred message %s code %d\n\n", error, code); } } bool verifysignature = true; lh >checklicenselocal(lh, verifysignature); if(lh >waserror(lh)) { const char error = lh >getlasterrormsg(lh); enum lserrorcode code = lh >getlasterror(lh); printf("error occurred message %s code %d\n\n", error, code); } lsinstallationfile pinstallfile = lh >checklicense(lh); if(pinstallfile) freelsinstallationfile(pinstallfile); if(lh >waserror(lh)) { const char error = lh >getlasterrormsg(lh); enum lserrorcode code = lh >getlasterror(lh); printf("error occurred message %s code %d\n\n", error, code); } license deactivation deactivating a license unbinds the device from the license, and decrements the number of total activations deactivating is done using the following method if(lh >deactivatelicense(lh)) printf("license deactivated successfully \n"); common errors the license checks can produce the following errors error definition elicensedisabled elicenseinactive elicenseexpired license is in invalid state (disabled, epired or inactive) eproductmismatcherror license does not belong to configured product edeviceerror license does not belong to current device edeviceblacklisted the device has been blacklisted eclocktamperederror detected cheating with system clock enointerneterror enetworktimeouterror eservererror connection related errors if there's no internet or an internal server error occured eunauthorizedclient eoauthrequired eoauthtokenexpired invalid client credentials license requires oauth authentication oauth token is expired this shouldn't happen as the sdk keeps track of its lifetime