Python Nalpeiron V10 Licensing library (NSL) functions

Files
file	cnsl.py
	Nalpeiron V10 Nalpeiron library licensing (NSL) functions.

Functions
def	cnsl.NSLDefineFunctions (oset, libHandle)
	Define the Licenseing library (NSL) functions from the C library. More...
def	cnsl.pyNSLValidateLibrary (custID, prodID)
	Verifies that the shared library you are accessing is the library you stamped at Nalpeiron's website. More...
def	cnsl.pyNSLGetVersion ()
	Gets the version of the NSL library being accessed. More...
def	cnsl.pyNSLGetComputerID ()
	Gets the computer ID of the current system. More...
def	cnsl.pyNSLGetHostName ()
	Gets the name of the SOAP server the library contacts for licensing information. More...
def	cnsl.pyNSLTestConnection2 (connTO, transTO)
	Tests the network connection to Nalpeiron. More...
def	cnsl.pyNSLSetCredentials (username, password, USERAUTH, dataSize, data)
	Set username and password for future logins to the Nalpeiron licensing server or for a user provided authentication callback function. More...
def	cnsl.pyNSLSetCredentialsSSO (ssoToken, inData)
	This function mirrors the functionality of NSLSetCredentials but uses a JWT (JSON Web Token) to gather the needed authentication information. More...
def	cnsl.pyNSLCheckCredentials ()
	Validate credentials passed into the library with NSLSetCredentials against any stored in the license file. More...
def	cnsl.pyNSLGetCredentials ()
	Get information from the last SetCredentials (or callback) call. More...
def	cnsl.pyNSLClearCredentials ()
	Clear username and password set with NSLSetCredentials. More...
def	cnsl.pyNSLGetLeaseExpSec ()
	Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the license lease expiration. More...
def	cnsl.pyNSLGetLeaseExpDate ()
	Retrieves the expiration of the license as a time/date string (Wed Jul 17 19:59:12 2013, for example). More...
def	cnsl.pyNSLGetMaintExpSec ()
	Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the maintenance period expiration. More...
def	cnsl.pyNSLGetMaintExpDate ()
	Retrieves the expiration of the maintenance period as a time/date string (Wed Jul 17 19:59:12 2013, for example). More...
def	cnsl.pyNSLGetSubExpSec ()
	Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the subscription expiration. More...
def	cnsl.pyNSLGetSubExpDate ()
	Retrieves the expiration of the subscription period as a time/date string (Wed Jul 17 19:59:12 2013, for example). More...
def	cnsl.pyNSLGetTrialExpSec ()
	Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the trial expiration. More...
def	cnsl.pyNSLGetTrialExpDate ()
	Retrieves the expiration of the trial period as a time/date string (Wed Jul 17 19:59:12 2013, for example). More...
def	cnsl.pyNSLGetLicenseStatus ()
	Retrieves the status of the current license. More...
def	cnsl.pyNSLGetVMInfo ()
	Retrieves the virtual machine information about the system. More...
def	cnsl.pyNSLGetLicenseInfo ()
	Retrieves the license type and activation type for the current license. More...
def	cnsl.pyNSLGetLibraryOptions ()
	Retrieves the library options specified at library creation. More...
def	cnsl.pyNSLGetLicenseCode ()
	Retrieves the license code used with the current license. More...
def	cnsl.pyNSLGetTimeStamp ()
	Retrieves the current time (seconds since epoch start) from the Nalpeiron daemon or server. More...
def	cnsl.pyNSLGetLicense (licenseCode, xmlRegInfo)
	Contacts the SOAP server for a new license or a license refresh. More...
def	cnsl.pyNSLObtainLicense (licenseCode, xmlRegInfo, specialID)
	Contacts the SOAP server for a new license or a license refresh. More...
def	cnsl.pyNSLReturnLicense (licenseCode)
	Returns the current license to the Nalpeiron server. More...
def	cnsl.pyNSLImportCertificate (licenseCode, certContainer)
	Imports a license from the given certificate. More...
def	cnsl.pyNSLGetActivationCertReq (licenseCode, xmlRegInfo)
	Generate an request for a activation certificate from the Nalpeiron server (ie offline activation). The resulting request can be emailed or otherwise sent to Nalpeiron. More...
def	cnsl.pyNSLRequestActivationCert (licenseCode, xmlRegInfo, specialID)
	Generate an request for a activation certificate from the Nalpeiron server (ie offline activation). More...
def	cnsl.pyNSLGetDeactivationCertReq (licenseCode)
	Generate a request for a deactivation certificate from the Nalpeiron server (ie offline deactivation). More...
def	cnsl.pyNSLGetNumbAvailProc ()
	A license may limit the number of simultaneous copies allowed to run on a specific computer. More...
def	cnsl.pyNSLCheckoutFeature (featureCode, licenseCode)
	Checkout one use of a "floating feature" from the Nalpeiron server or daemon. More...
def	cnsl.pyNSLReturnFeature (featureCode, licenseCode)
	Return one use of a "floating feature" to the Nalpeiron server or daemon. More...
def	cnsl.pyNSLGetFeatureStatus (featureCode)
	Checks the current license for the status of featureName. More...
def	cnsl.pyNSLCheckoutPool (poolCode, poolAmt, licenseCode)
	Withdraws a specified number of elements from an element pool. More...
def	cnsl.pyNSLReturnPool (poolCode, poolAmt, licenseCode)
	Returns a specified number of elements to an element pool. More...
def	cnsl.pyNSLGetPoolInfo (poolCode)
	Get the number of pool elements current checked out along with the status of an element pool. More...
def	cnsl.pyNSLCheckoutTokens (tokenCode, tokenAmt, licenseCode)
	Withdraws a specified number of tokens from an token pool on the Nalpeiron server. More...
def	cnsl.pyNSLConsumeTokens (tokenCode, tokenAmt, licenseCode)
	Consumes the indicated number of tokens. More...
def	cnsl.pyNSLReturnTokens (tokenCode, tokenAmt, licenseCode)
	Returns the indicated number of tokens. More...
def	cnsl.pyNSLGetTokenInfo (tokenCode)
	Get the number of tokens current checked out along with the status of an token. More...
def	cnsl.pyNSLGetUDFValue (udfName)
	Retrieve the value of a UDF (AA) More...
def	cnsl.pyNSLReadSecStore (rawkey, storeName)
	Retrieve the value of a Secure Store. More...
def	cnsl.pyNSLWriteSecStore (rawkey, storeName, storeValue)
	Set the value of a Secure Store. More...
def	cnsl.pyNSLRemoteCallV (rpcName, rpcArgs)
	Call a remote proceedure at the Nalpeiron server. More...
def	cnsl.pyNSLGetErrorMsg (nalpErrorNo)
	Get a descriptive string for nalpeiron error codes. More...

Variables
int	cnsl.offset = 0

Detailed Description

Function Documentation

def cnsl.NSLDefineFunctions	(		oset,
			libHandle
	)

Define the Licenseing library (NSL) functions from the C library.

Parameters

oset	Security offset as calculated in nalpParse.py
libHandle	a library handle as returned by cytpes.cdll.LoadLibrary

Returns

def cnsl.pyNSLCheckCredentials

(

)

Validate credentials passed into the library with NSLSetCredentials against any stored in the license file.

When a program with an ABL license has been shutdown without a ReturnLicense or a ClearCredentials the credentials are cached in the license file. Once the library is restarted before the license file's entitlements can be accessed those credentials must be verified. This state is indicated by a -70 license status. The verification is done using this call.

If the cached credentials are a username/password combination that was initially validated by the Nalpeiron server then the username and password passed to NSLSetCredentials will be validated against those stored in the license file. NOTE the password is never stored or transmitted in plain text.

If the cached credentials were initially verified by a callback function then that callback will be called to verify the password and username passed to NSLSetCredentials.

If the cache credentials were initially verified by a callback with authentication token then that token will need to be passed back to the library from the callback function. The username and token will be verified against those stored in the license file.

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLCheckoutFeature	(		featureCode,
			licenseCode
	)

Checkout one use of a "floating feature" from the Nalpeiron server or daemon.

On return featureStatus will contain the feature status code. In addition to checking the return value of the function, the feature status code must also be checked to ensure a feature seat was available.

Parameters

featureCode	a string containing the five (5) character feature code of the feature to be checked out.
licenseCode	the license number of the current, valid system license

Returns

Tuple retVal, featureStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
featStatus.value a 32 bit int containing the feature status (FEATSTATUS)

def cnsl.pyNSLCheckoutPool	(		poolCode,
			poolAmt,
			licenseCode
	)

Withdraws a specified number of elements from an element pool.

Parameters

poolCode	a string containing the five (5) character pool code of the pool to be drawn from.
poolAmt	the number of elements to withdraw from the pool
licenseCode	the license number of the current, valid system license

Returns

Tuple retVal, poolStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
pStat.value a 32 bit int containing the pool status (FEATSTATUS)

def cnsl.pyNSLCheckoutTokens	(		tokenCode,
			tokenAmt,
			licenseCode
	)

Withdraws a specified number of tokens from an token pool on the Nalpeiron server.

Parameters

tokenCode	a string containing the five (5) character code of the token pool to be drawn from.
tokenAmt	the number of tokens to withdraw from the pool
licenseCode	the license number of the current, valid system license

Returns

Tuple retVal, tokenStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
tStat.value a 32 bit int containing status of the token pool (FEATSTATUS)

def cnsl.pyNSLClearCredentials

(

)

Clear username and password set with NSLSetCredentials.

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLConsumeTokens	(		tokenCode,
			tokenAmt,
			licenseCode
	)

Consumes the indicated number of tokens.

The number of locally held tokens (as obtained via NSLCheckoutTokens) will be decremented by the indicated amount. NOTE locally held tokens CANNOT be returned to the server. Locally held tokens will be LOST if the license file is deleted.

Parameters

tokenCode	a string containing the five (5) character code of the token pool to be drawn from.
tokenAmt	the number of tokens to be consumed (ie removed from locally held pool).
licenseCode	the license number of the current, valid system license

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLGetActivationCertReq	(		licenseCode,
			xmlRegInfo
	)

Generate an request for a activation certificate from the Nalpeiron server (ie offline activation). The resulting request can be emailed or otherwise sent to Nalpeiron.

Deprecated:

June 2020.

This function is deprecated and will be removed from a future version of the NSL library. Use pyNSLRequestActivationCert (pyNSLRequestActivationCert) instead.

Parameters

licenseCode	the license number to be used in creating the certificate request. If the licenseCode is NULL, an attempt for a trial license certificate will be made.
xmlRegInfo	Optional registration information may be passed to the Nalpeiron server using the xmlRegInfo string. If there is no registration information, this pointer should be NULL.

Returns

Tuple retVal, certificate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
cert on success the resulting certificate request will be passed back

def cnsl.pyNSLGetComputerID

(

)

Gets the computer ID of the current system.

Returns

Tuple retVal, computerID
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
computerID = "" on error
computerID = string containing the computer ID

def cnsl.pyNSLGetCredentials

(

)

Get information from the last SetCredentials (or callback) call.

Returns

lastRet a pointer to a 64 bit signed integer that will contain the last return value from a callback provided to NSLSetCredentials.

authToken contains the last authentication token returned to the library from the authentication callback. authToken must be cleared with a call to NSLFree.

username contains the last username set with NSLSetCredentials. username must be cleared with a call to NSLFree.

inData the last data sent to the callback. inData must be cleared with a call to NSLFree.

outData the last data received from the callback. outData must be cleared with a call to NSLFree.

def cnsl.pyNSLGetDeactivationCertReq

(

licenseCode

)

Generate a request for a deactivation certificate from the Nalpeiron server (ie offline deactivation).

The resulting request can be emailed or otherwise sent to Nalpeiron.

Parameters

licenseCode

the license number used to obtain the license.

Returns

Tuple retVal, certificate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
cert on success the resulting certificate request will be passed back

def cnsl.pyNSLGetErrorMsg

(

nalpErrorNo

)

Get a descriptive string for nalpeiron error codes.

Parameters

nalpErrorNo

is a negative return value from one of the Nalpeiron functions

Returns

Tuple retVal, errorMessage
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
errMsg a string containing the error message
NOTE - GetErrorMsg is really a call shared by NSA and NSL. As such it does not use the security offset Get the complete filename and path of log file, cache file, system info file, etc. For log file pass ".log" into extension. filepath should be freed with NSLFree by the caller.

Tuple retVal, filepath
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
fpath a string containing the complete file path
NOTE - GetFilepath is really a call shared by NSA and NSL. As such it does not use the security offset

def cnsl.pyNSLGetFeatureStatus

(

featureCode

)

Checks the current license for the status of featureName.

Status if returned in featureStatus.

Parameters

featureCode

a string containing the five (5) character feature code of the feature to be checked out.

Returns

Tuple retVal, featureStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
featStatus.value a 32 bit int containing the feature status (FEATSTATUS)

def cnsl.pyNSLGetHostName

(

)

Gets the name of the SOAP server the library contacts for licensing information.

Returns

Tuple retVal, hostname
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
hostname = "" on error
hostname = string containing the hostname of licensing server

def cnsl.pyNSLGetLeaseExpDate

(

)

Retrieves the expiration of the license as a time/date string (Wed Jul 17 19:59:12 2013, for example).

Returns

Tuple retVal, expDate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
expDate = string containing the time/date of expiration.

def cnsl.pyNSLGetLeaseExpSec

(

)

Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the license lease expiration.

If the item has expired, the number of seconds remaining will be zero. epochDate is the absolute expiration date in epoch sec. If epochDate = NULL then no epochDate value is retrieved.

Returns

Tuple retVal, sec, expEpoch
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
sec.value = unsigned 32 bit integer representing the seconds until expiration expEpoch.value = unsigned 32 bit integer containing the epoch time of expiration

def cnsl.pyNSLGetLibraryOptions

(

)

Retrieves the library options specified at library creation.

Returns

Tuple retVal, libraryOptions
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
libraryOptions.value = a 64 bit unsigned integer describing license options (LIBOPTS)

def cnsl.pyNSLGetLicense	(		licenseCode,
			xmlRegInfo
	)

Contacts the SOAP server for a new license or a license refresh.

Deprecated:

June 2020.

This function is deprecated and will be removed from a future version of the NSL library. Use pyNSLObtainLicense (pyNSLObtainLicense) instead.

Parameters

licenseCode	If licenseCode is non-NULL that number is used in the attempt to retrieve a license. If the licenseCode is NULL, the function attempts to retrieve a trial license.
xmlRegInfo	Optional registration information may be passed to the Nalpeiron server using the xmlRegInfo string. If there is no registration information, this pointer should be NULL.

Returns

Tuple retVal, licenseStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licStat.value = a 32 bit int containing the license status (License status values)

def cnsl.pyNSLGetLicenseCode

(

)

Retrieves the license code used with the current license.

NOTE: a license code will only be present if one has already been assigned to the current license via NSLGetLicense, NSLImportCert, etc.

Returns

Tuple retVal, licenseCode
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licenseCode = a string containing the license code

def cnsl.pyNSLGetLicenseInfo

(

)

Retrieves the license type and activation type for the current license.

Returns

Tuple retVal, licenseType, actType
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licenseType.value = a 32 bit integer describing license type (LICTYPE) actType.value = a 32 bit integer describing activation type (ACTTYPE)

def cnsl.pyNSLGetLicenseStatus

(

)

Retrieves the status of the current license.

Negative values indicate an invalid license state.

Returns

Tuple retVal, licStat
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licStat.value = a 32 bit integer containing the license status (License status values)

def cnsl.pyNSLGetMaintExpDate

(

)

Retrieves the expiration of the maintenance period as a time/date string (Wed Jul 17 19:59:12 2013, for example).

Returns

Tuple retVal, expDate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
expDate = string containing the time/date of expiration.

def cnsl.pyNSLGetMaintExpSec

(

)

Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the maintenance period expiration.

If the item has expired, the number of seconds remaining will be zero. epochDate is the absolute expiration date in epoch sec. If epochDate = NULL then no epochDate value is retrieved.

Returns

Tuple retVal, sec, expEpoch
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
sec.value = unsigned 32 bit integer representing the seconds until expiration expEpoch.value = unsigned 32 bit integer containing the epoch time of expiration

def cnsl.pyNSLGetNumbAvailProc

(

)

A license may limit the number of simultaneous copies allowed to run on a specific computer.

This limit is disabled by default and, if desired, must be enabled on the Nalpeiron server. The number of copies available is set to noProcs+1 and availProc is the number of copies still available for use. When an application instance is started and returns availProc=0, the number of instances exceeds the maximum allowed and this instance should be terminated.

When disabled, this fuction will always return zero (0) as noProcs and one (1) as the number of availProc. NOTE limiting the number of processes allowed on a machine ("Number of concurrent Processes" setting on server) is not affected by the "Concurrency Mode" setting.

Returns

Tuple retVal, maxProc, availProc
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
maxProc.value a unsigned 32 bit int containing max number of proc allowed to run availProc.value a unsigned 32 bit int containing number of proc still available

def cnsl.pyNSLGetPoolInfo

(

poolCode

)

Get the number of pool elements current checked out along with the status of an element pool.

NOTE this function replaces NSLGetPoolStatus (NSLGetPoolStatus).

Parameters

poolCode

a string containing the five (5) character pool code of the pool to be drawn from.

Returns

Tuple retVal, poolMax, poolAmount, poolStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
pMax.value an unsigned 32 bit int containing the maximum number of pool elements pAmt.value an unsigned 32 bit int containing the number of elements checked out pStat.value a 32 bit int containing the status of the pool (FEATSTATUS)

def cnsl.pyNSLGetSubExpDate

(

)

Retrieves the expiration of the subscription period as a time/date string (Wed Jul 17 19:59:12 2013, for example).

Returns

Tuple retVal, expDate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
expDate = string containing the time/date of expiration.

def cnsl.pyNSLGetSubExpSec

(

)

Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the subscription expiration.

If the item has expired, the number of seconds remaining will be zero. epochDate is the absolute expiration date in epoch sec. If epochDate = NULL then no epochDate value is retrieved.

Returns

Tuple retVal, sec, expEpoch
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
sec.value = unsigned 32 bit integer representing the seconds until expiration expEpoch.value = unsigned 32 bit integer containing the epoch time of expiration

def cnsl.pyNSLGetTimeStamp

(

)

Retrieves the current time (seconds since epoch start) from the Nalpeiron daemon or server.

Returns

Tuple retVal, timeStamp
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
timeStamp.value = a unsigned 64 bit int containing seconds since epoch start.

def cnsl.pyNSLGetTokenInfo

(

tokenCode

)

Get the number of tokens current checked out along with the status of an token.

Parameters

tokenCode

a string containing the five (5) character code of the token pool to be drawn from.

Returns

Tuple retVal, tokenMax, tokenAmount, tokenStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
pMax.value an unsigned 32 bit int containing the maximum number of pool elements pAmt.value an unsigned 32 bit int containing the number of elements checked out pStat.value a 32 bit int containing the status of the pool (FEATSTATUS)

def cnsl.pyNSLGetTrialExpDate

(

)

Retrieves the expiration of the trial period as a time/date string (Wed Jul 17 19:59:12 2013, for example).

Returns

Tuple retVal, expDate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
expDate = string containing the time/date of expiration.

def cnsl.pyNSLGetTrialExpSec

(

)

Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the trial expiration.

If the item has expired, the number of seconds remaining will be zero. epochDate is the absolute expiration date in epoch sec. If epochDate = NULL then no epochDate value is retrieved.

Returns

Tuple retVal, sec, expEpoch
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
sec.value = unsigned 32 bit integer representing the seconds until expiration expEpoch.value = unsigned 32 bit integer containing the epoch time of expiration

def cnsl.pyNSLGetUDFValue

(

udfName

)

Retrieve the value of a UDF (AA)

Parameters

udfName

a string containing the five (5) character UDF code of the value to be accessed

Returns

Tuple retVal, udfValue
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
uValue a string containing the UDF value

def cnsl.pyNSLGetVersion

(

)

Gets the version of the NSL library being accessed.

Returns

Tuple retVal, version
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
version = "" on error
version = string containing the library version on success

def cnsl.pyNSLGetVMInfo

(

)

Retrieves the virtual machine information about the system.

Returns

Tuple retVal, isVM, vmType
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
isVM.value = a 32 bit integer 1 or 0 (1 for is a VM, 0 for not a VM) vmType = A string containing a description of the VM type (Virtual machine types).

def cnsl.pyNSLImportCertificate	(		licenseCode,
			certContainer
	)

Imports a license from the given certificate.

Parameters

licenseCode	the license number associated with the given license certificate
certContainer	Either the certificate itself passed in as a NULL terminated string or the full path to a file containing the certificate. NOTE The keyword "clear" may be passed as a string for the certContainer. If this is done, any existing receipt on the end system will be removed allowing generation of a fresh activation request.

Returns

Tuple retVal, licenseStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licStat.value = a 32 bit int containing the license status (License status values)

def cnsl.pyNSLObtainLicense	(		licenseCode,
			xmlRegInfo,
			specialID
	)

Contacts the SOAP server for a new license or a license refresh.

Parameters

licenseCode	If licenseCode is non-NULL that number is used in the attempt to retrieve a license. If the licenseCode is NULL, the function attempts to retrieve a trial license.
xmlRegInfo	Optional registration information may be passed to the Nalpeiron server using the xmlRegInfo string. If there is no registration information, this pointer should be NULL.
specialID	Optional user supplied string. If present in an activation certificate request the Nalpeiron server will place the supplied value in a special application agility field call $SpecialID. This field can be queried using pyNSLGetUDFValue (pyNSLGetUDFValue) to access the value from the calling program.

Returns

Tuple retVal, licenseStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licStat.value = a 32 bit int containing the license status (License status values)

def cnsl.pyNSLReadSecStore	(		rawkey,
			storeName
	)

Retrieve the value of a Secure Store.

Parameters

rawkey	a string containing the rawkey used for encryption of the Secure Store. The rawkey is interpreted as binary data and IS NOT converted to UTF-8 or any other encoding before use.
storeName	a string containing the five (5) character Secure Store code of the value to be accessed

Returns

Tuple retVal, storeValue
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
uValue a string containing the Secure Store value

def cnsl.pyNSLRemoteCallV	(		rpcName,
			rpcArgs
	)

Call a remote proceedure at the Nalpeiron server.

Alternative entry to NSL's RPC using arrays of pointers to UTF-8 encoded, NULL terminated strings. The final entry in each array is REQUIRED to be a NULL pointer.

Parameters

rpcName	a string containing the name of the remote proceedure to be accessed.
rpcArgs	a list containing comma separated items in the form argName1,argVal1,argName2,argVal2,... That is the names of the variables to be passed to the server fuction, the value of that argument.

Returns

Tuple retVal, rpcReturn
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
rpcRet a string containing the return value of the call (if any)

def cnsl.pyNSLRequestActivationCert	(		licenseCode,
			xmlRegInfo,
			specialID
	)

Generate an request for a activation certificate from the Nalpeiron server (ie offline activation).

The resulting request can be emailed or otherwise sent to Nalpeiron.

Parameters

licenseCode	the license number to be used in creating the certificate request. If the licenseCode is NULL, an attempt for a trial license certificate will be made.
xmlRegInfo	Optional registration information may be passed to the Nalpeiron server using the xmlRegInfo string. If there is no registration information, this pointer should be NULL.
specialID	Optional user supplied string. If this string is present in the certificate request then the Nalpeiron server will write it to a special application agility field named $SpecialID. This field may be queried using NSLGetUDFValue (NSLGetUDFValue) to obtain the string for use in the calling program.

Returns

Tuple retVal, certificate
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
cert on success the resulting certificate request will be passed back

def cnsl.pyNSLReturnFeature	(		featureCode,
			licenseCode
	)

Return one use of a "floating feature" to the Nalpeiron server or daemon.

Parameters

featureCode	a string containing the five (5) character feature code of the feature to be checked out.
licenseCode	the license number of the current, valid system license

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLReturnLicense

(

licenseCode

)

Returns the current license to the Nalpeiron server.

Parameters

licenseCode

The license code associated with the current license

Returns

Tuple retVal, licenseStatus
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)
licStat.value = a 32 bit int containing the license status (License status values)

def cnsl.pyNSLReturnPool	(		poolCode,
			poolAmt,
			licenseCode
	)

Returns a specified number of elements to an element pool.

Parameters

poolCode	a string containing the five (5) character pool code of the pool to be drawn from.
poolAmt	the number of elements to return to the pool
licenseCode	the license number of the current, valid system license

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLReturnTokens	(		tokenCode,
			tokenAmt,
			licenseCode
	)

Returns the indicated number of tokens.

The number of locally held tokens (as obtained via NSLCheckoutTokens) will be decremented by the indicated amount and that count will be returned to the Nalpeiron server.

Parameters

tokenCode	a string containing the five (5) character code of the token pool to be drawn from.
tokenAmt	the number of tokens to be returned (ie removed from locally held pool).
licenseCode	the license number of the current, valid system license

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLSetCredentials	(		username,
			password,
			USERAUTH,
			dataSize,
			data
	)

Set username and password for future logins to the Nalpeiron licensing server or for a user provided authentication callback function.

If a callback is provided, the username, password and data will be passed to the function for validation. The library will consider any return >= 0 to be validation success. If no callback is provided the username and password will be used to obtain a license from the Nalpeiron server rather than the license code. NOTE this function only sets these values locally for the library. The username and password are NOT verified until the next call to the Nalpeiron server to retrieve a license.

Parameters

username	either a NULL terminated, UTF-8 encoded string containing a valid username for the Nalpeiron server OR a UTF-8 encoded string that will be passed to the userAuthenticator function. NOTE in the case that a userAuthenticator function is to be used neither the username nor the password are stored in the license file. This means that the NSLSetCredentials function should be called after any library initialization.
password	a NULL terminated, UTF-8 encoded string containing a valid password for the Nalpeiron server OR a UTF-8 encoded string that will be passed to the userAuthenticator function. In the case of the password to be used at Nalpeiron for authentication, the password is never recorded nor transmitted in plain text. If the password is to be passed to an authentication function (ie userAuthenticator != NULL), then the password is NOT stored in the license file. This means that the NSLSetCredentials function should be called after any library initialization.
USERAUTH	if NULL then autentication will take place at Nalpeiron. If non-NULL then the pointer will be used as a user supplied callback with the form int (*userAuth)(const char *uname, const char *pwd, void *data) This function will be called to authenticate the username/password combination. The function will have the username, password, and data parameters passed to it exactly as the were passed to the NSLSetCredentials function. This means, for instance, that you could encrypt the password before passing it to NSLSetCredentials for security purposes (of course, that would mean, the userAuthenticator function would need to be able to use an encrypted password). nslTerm.py gives an example of how to set up and use a callback.
data	an optional bit of data that, if non-NULL, will be passed into the userAuthenticator function. A copy of this data is made and stored in memory by the library. data is NOT stored on disk at any time which means it is lost when the library is closed. This means that the NSLSetCredentials function should be called after any library initialization.
dataSize	the size of the data pointed to by data. The maximum allowable size is 4k (4096 bytes).

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLSetCredentialsSSO	(		ssoToken,
			inData
	)

This function mirrors the functionality of NSLSetCredentials but uses a JWT (JSON Web Token) to gather the needed authentication information.

Parameters

ssoToken	A valid NULL terminated jwt presented as a string. The jwt will be validated before being used as an authentication source. The standard JWT validation method is used which will require access to the IDP for jwks information. A local IDP may be used.
inData	Should be set to NULL by the caller. Currently only used for ABLUSER claim override.

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLTestConnection2	(		connTO,
			transTO
	)

Tests the network connection to Nalpeiron.

Parameters

connTO	if non-zero the number of milliseconds the library should wait for the initial connection to the Nalpeiron server to complete before timing out. If 0, the values passed into NalpLibOpen are used. This value overrides any connection timeout specified at library initialization.
transTO	if non-zero the number of milliseconds the library should wait for the entire transaction (this includes the connection time above, name look-up time, transfer time, etc) to the Nalpeiron server to complete before timing out. If 0, the passed into NalpLibOpen are used. This value overrides any transaction timeout specified at library initialization.

Returns

= 0 If the call succeeded

< 0 A negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLValidateLibrary	(		custID,
			prodID
	)

Verifies that the shared library you are accessing is the library you stamped at Nalpeiron's website.

It does this by checking the customerID and productID sent in against the stamped values. Any negative return value, even if it is not a known error code, is cause to consider the library invalid.

Parameters

custID	a unsigned 32 bit integer containing your Nalpeiron customer ID. NOTE the library uses ONLY the last 5 non-zero digits of your full customer ID. That is, if your customer ID is 12340005678 then the customer ID used in conjuction with the library would be 5678.
prodID	a unsigned 32 bit integer containing your Nalpeiron product ID. NOTE the library uses ONLY the last 5 non-zero digits of your full product ID. That is, if your customer ID is 12340005678 then the product ID used in conjuction with the library would be 5678.

Returns

= 0(zero) is returned if the customerID/productID passed into the function match those from the library.

< 0 On mismatch, a negative error value is returned (Nalpeiron V10 error returns)

def cnsl.pyNSLWriteSecStore	(		rawkey,
			storeName,
			storeValue
	)

Set the value of a Secure Store.

Parameters

rawkey	a string containing the rawkey used for encryption of the Secure Store. The rawkey is interpreted as binary data and IS NOT converted to UTF-8 or any other encoding before use.
storeName	a string containing the five (5) character Secure Store code of the value to be accessed
storeValue	a string containing the value to be written to the the Secure Store. The storeValue is stored as-is and IS NOT converted to UTF-8 or any other encoding before use.

Returns

retVal
retVal = 0 If the call succeeded
retVal < 0 A negative error value is returned (Nalpeiron V10 error returns)

Variable Documentation

int cnsl.offset = 0