Files
file	nslH.h
	Licensing (NSL) Nalpeiron V10 library functions.

Functions
int	NSLValidateLibrary (uint32_t custID, uint32_t 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. More...

int	NSLGetVersion (char **version)
	Gets the version of the NSL library being accessed. More...

int	NSLGetComputerID (char **computerID)
	Gets the computer ID of the current system. More...

int	NSLGetHostName (char **hostName)
	Gets the name of the SOAP server the library contacts for licensing information. More...

int	NSLTestConnection ()
	Tests the network connection to Nalpeiron. More...

int	NSLTestConnection2 (uint32_t connTimeOut, uint32_t transTimeOut)
	Tests the network connection to Nalpeiron. More...

int	NSLSetCredentials (const char username, const char password, USERAUTH userAuthenticator, uint32_t inDataSize, void *inData)
	Set username and password in the Nalpeiron library for future logins to the Nalpeiron licensing server or for a user provided authentication callback function. The credentials must already exist on the Nalpeiron server or the user provided authentication system. More...

int	NSLSetCredentialsSSO (const unsigned char ssoToken, uint64_t ssoExpEpoch, char *inData)
	This function mirrors the functionality of NSLSetCredentials but uses a JWT (JSON Web Token) to gather the needed authentication information. More...

int	NSLCheckCredentials ()
	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 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. More...

int	NSLGetCredentials (int64_t lastRet, char username, void inData, void *outData)
	Get information from the last SetCredentials (or callback) call. NOTE The values returned by NSLGetCredentials may or may not be the same as those cached in the license file. More...

int	NSLClearCredentials ()
	Clear username, password, inData, outData and authToken set with NSLSetCredentials and/or a call to the authentication callback. Clear credentials must be called when switching authentication types and/or switching between different credential sets. More...

int	NSLGetLeaseExpSec (uint32_t sec, uint32_t expEpoch)
	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. More...

int	NSLGetLeaseExpDate (char **Date)
	Retrieves the expiration of the license lease as a time/date string (Wed Jul 17 19:59:12 2013, for example). More...

int	NSLGetMaintExpSec (uint32_t sec, uint32_t expEpoch)
	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. More...

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

int	NSLGetSubExpSec (uint32_t sec, uint32_t expEpoch)
	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. More...

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

int	NSLGetTrialExpSec (uint32_t sec, uint32_t expEpoch)
	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. More...

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

int	NSLGetLicenseStatus (int32_t *licenseStatus)
	Retrieves the status of the current license. Negative values indicate an invalid license state. More...

int	NSLGetVMInfo (uint32_t isVM, char *vmType)
	Retrieves the virtual machine information about the system. More...

int	NSLGetLicenseInfo (uint32_t licenseType, uint32_t actType)
	Retrieves the license type and activation type for the current license. More...

int	NSLGetLibraryOptions (uint64_t *libOptions)
	Retrieves information about the choices (HDSN, HTTPS, etc) made at library creation. More...

int	NSLGetLicenseCode (char **licenseCode)
	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 NSLObtainLicense, NSLImportCertificate, etc. More...

int	NSLGetTimeStamp (uint64_t *timeStamp)
	Retrieves the current time (seconds since epoch start) from the Nalpeiron daemon or server. More...

int	NSLGetLicense (const char authentication, int32_t licenseStatus, const char *xmlRegInfo)
	Contacts the SOAP server for a new license or a license refresh. NSLGetLicense must be called at least once after the library is initialized to maintain a license from the Nalpeiron daemon as it is responsible for starting and/or re-establishing the heartbeat to a Nalpeiron daemon. This function is deprecated use NSLObtainLicense instead. More...

int	NSLObtainLicense (const char authentication, int32_t licenseStatus, const char xmlRegInfo, const char specialID)
	Contacts the SOAP server for a new license or a license refresh. NSLObtainLicense must be called at least once after the library is initialized to maintain a license from the Nalpeiron daemon as it is responsible for starting and/or re-establishing the heartbeat to a Nalpeiron daemon. More...

int	NSLReturnLicense (const char authentication, int32_t licenseStatus)
	Returns the current license to the Nalpeiron server. More...

int	NSLImportCertificate (const char authentication, int32_t licenseStatus, char *certContainer)
	Imports a license from the given certificate. More...

int	NSLGetActivationCertReq (const char authentication, const char xmlRegInfo, char **cert)
	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. Function is deprecated use NSLRequestActivationCert instead. More...

int	NSLRequestActivationCert (const char authentication, const char xmlRegInfo, const char specialID, char *cert)
	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...

int	NSLGetDeactivationCertReq (const char authentication, char *cert)
	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. More...

int	NSLGetNumbAvailProc (uint32_t maxProc, uint32_t availProc)
	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. More...

int	NSLCheckoutFeature (const char featureName, int32_t featureStat, const char *authentication)
	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. More...

int	NSLReturnFeature (const char featureName, const char authentication)
	Return one use of a "floating feature" to the Nalpeiron server or daemon. More...

int	NSLGetFeatureStatus (const char featureName, int32_t featureStatus)
	Checks the current license for the status of featureName. Status is returned in featureStatus. More...

int	NSLCheckoutPool (const char poolName, uint32_t poolAmt, int32_t poolStatus, const char *authentication)
	Withdraws a specified number of elements from an element pool. More...

int	NSLReturnPool (const char poolName, uint32_t poolAmt, const char authentication)
	Returns a specified number of elements to an element pool. More...

int	NSLGetPoolStatus (const char poolName, uint32_t poolAmt, int32_t *poolStatus)
	Get the number of pool elements current checked out along with the status of an element pool. Function is deprecated use NSLGetPoolInfo (NSLGetPoolInfo) instead. More...

int	NSLGetPoolInfo (const char poolName, uint32_t poolMax, uint32_t poolAmt, int32_t poolStatus)
	Get the number of pool elements current checked out along with the status of an element pool. NOTE this function replaces NSLGetPoolStatus (NSLGetPoolStatus). More...

int	NSLCheckoutTokens (const char tokenName, uint32_t tokenAmt, int32_t tokenStatus, const char *authentication)
	Withdraws a specified number of tokens from an token pool on the Nalpeiron server. More...

int	NSLConsumeTokens (const char tokenName, uint32_t tokenAmt, const char authentication)
	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 will be LOST if the license file is deleted. More...

int	NSLReturnTokens (const char poolName, uint32_t poolAmt, const char authentication)
	Returns a specified number of unconsumed tokens to an token pool. More...

int	NSLGetTokenInfo (const char tokenName, uint32_t tokenMax, uint32_t tokenAmt, int32_t tokenStatus)
	Get the number of tokens current checked out along with the status of an token. More...

int	NSLGetUDFValue (const char udfName, char *udfValue)
	Retrieve the value of a UDF (AA) More...

int	NSLReadSecStore (const char rawKey, const char storeName, char **storeValue)
	Retrieve information contained in a secure storage area. More...

int	NSLWriteSecStore (uint32_t storeSize, const char rawKey, const char storeName, const char *storeValue)
	Store information in a secure storage area. More...

int	NSLRemoteCall (const char rpcName, char *rpcReturn,...)
	Call a remote proceedure at the Nalpeiron server. The parameters of this function begin with the remote proceedure's name (rpcName). The elipses represent the parameters for the remote function call. This argument list may be thought of as varName1, var1, varName2, var2, ... varNamen, varn, (char )NULL. This list of arguments MUST be terminated with a null pointer and the null pointer must be cast to a char . As many name/value pairs as needed may be passed into the function. More...

int	NSLRemoteCallV (const char rpcName, char rpcReturn, char rpcVarNames, char *rpcVarVals)
	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. More...

int	NSLFree (void *memptr)
	The NSLFree functions is available to free any memory allocated by the NSL library. This function is mandatory on windows as depending on how your binary is built, your final binary may have a different heap than the NSL library. This function is provided to ensure that memory allocated from the NSL heap is freed there. NSLFree should be used on the memory returned from the NSL library. More...

Detailed Description

Licensing library functions from Nalpeiron V10

Function Documentation

int NSLCheckCredentials ( )

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 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)

int NSLCheckoutFeature	(	const char *	featureName,
		int32_t *	featureStat,
		const char *	authentication
	)

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

featureName	a NULL terminated, UTF-8 encoded string containing the five (5) character feature code of the feature to be checked out.
featureStat	the status of the checked-out feature (FEATSTATUS)
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLCheckoutPool	(	const char *	poolName,
		uint32_t	poolAmt,
		int32_t *	poolStatus,
		const char *	authentication
	)

Withdraws a specified number of elements from an element pool.

Parameters

poolName	a NULL terminated, UTF-8 encoded 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
poolStatus	the status of the pool (FEATSTATUS)
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLCheckoutTokens	(	const char *	tokenName,
		uint32_t	tokenAmt,
		int32_t *	tokenStatus,
		const char *	authentication
	)

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

Parameters

tokenName	a NULL terminated, UTF-8 encoded 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
tokenStatus	the status of the pool (FEATSTATUS)
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLClearCredentials ( )

Clear username, password, inData, outData and authToken set with NSLSetCredentials and/or a call to the authentication callback. Clear credentials must be called when switching authentication types and/or switching between different credential sets.

NSLClearCredentials may only be called when no valid license exists. NOTE for the purposes of NSLClearCredentials a license status of -70 (ABL cached credentials need validattion) counts as a valid license. (ie license status <= 0).

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

int NSLConsumeTokens	(	const char *	tokenName,
		uint32_t	tokenAmt,
		const char *	authentication
	)

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 will be LOST if the license file is deleted.

Parameters

tokenName	a NULL terminated, UTF-8 encoded string containing the five (5) character code of the token pool that was drawn from.
tokenAmt	the number of tokens to be consumed (ie removed from locally held tokens).
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLFree ( void * memptr )

The NSLFree functions is available to free any memory allocated by the NSL library. This function is mandatory on windows as depending on how your binary is built, your final binary may have a different heap than the NSL library. This function is provided to ensure that memory allocated from the NSL heap is freed there. NSLFree should be used on the memory returned from the NSL library.

Parameters

memptr a pointer to the memory to be freed.

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

int NSLGetActivationCertReq	(	const char *	authentication,
		const char *	xmlRegInfo,
		char **	cert
	)

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. Function is deprecated use NSLRequestActivationCert instead.

Deprecated:: June 2020 This functions is deprecated and will be removed from a future version of the NSL library. Use NSLRequestActivationCert (NSLRequestActivationCert) instead

Parameters

authentication	the license number or username (ABL) to be used in creating the certificate request. If the licenseNo is NULL and licensing is NOT ABL, 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.
cert	on success the resulting certificate request will be passed back in this parameter as a NULL terminated string. cert should be freed with NSLFree.

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

int NSLGetComputerID ( char ** computerID )

Gets the computer ID of the current system.

Parameters

computerID on success contains the computer ID of the current system. computerID should be freed with NSLFree.

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

int NSLGetCredentials	(	int64_t *	lastRet,
		char **	username,
		void **	inData,
		void **	outData
	)

Get information from the last SetCredentials (or callback) call. NOTE The values returned by NSLGetCredentials may or may not be the same as those cached in the license file.

Parameters

lastRet	a pointer to a 64 bit signed integer that will contain the last return value from a callback provided to NSLSetCredentials.
username	contains the last username set with NSLSetCredentials. username must be cleared with a call to NSLFree. NOTE if the authentication method is ABL/SSO AND you have over ridden the username in the JWT with a supplemental username then this function will display the supplemental user name and NOT the username from the JWT.
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.

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

int NSLGetDeactivationCertReq	(	const char *	authentication,
		char **	cert
	)

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

authentication	the license number or username (ABL) used to obtain the license.
cert	on success the resulting certificate request will be passed back in this parameter as a NULL terminated string. cert should be freed with NSLFree.

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

int NSLGetFeatureStatus	(	const char *	featureName,
		int32_t *	featureStatus
	)

Checks the current license for the status of featureName. Status is returned in featureStatus.

Parameters

featureName	a NULL terminated, UTF-8 encoded string containing the five (5) character feature code of the feature to be checked out.
featureStatus	the status of the checked-out feature (FEATSTATUS)

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

int NSLGetHostName ( char ** hostName )

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

Parameters

hostName contains the hostname of the SOAP server used by the library. hostName should be freed with NSLFree.

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

int NSLGetLeaseExpDate ( char ** Date )

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

Parameters

Date	contains the date of the license expiration. If the license has expired the current date is retrieved. Date should be freed with NSLFree.

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

int NSLGetLeaseExpSec	(	uint32_t *	sec,
		uint32_t *	expEpoch
	)

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.

Parameters

sec	on success contains the the number of seconds remaining in the current lease.
expEpoch	if non-NULL, will contain the absolute expiration of the lease in epoch seconds.

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

int NSLGetLibraryOptions ( uint64_t * libOptions )

Retrieves information about the choices (HDSN, HTTPS, etc) made at library creation.

Parameters

libOptions a bit field consisting of on/off information for library creation options: BIT MEANING 0 Reserved 1 NSA privacy enabled 2 VM detection 3 HDSN 4 Reserved 5 HTTPS 6 Remove Dir Check 7 Continue if HDSN unobtainable 8 JWT validation fallback cert bundle enabled 9 Treat HyperV host as physical machine 10 Currently unused

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

int NSLGetLicense	(	const char *	authentication,
		int32_t *	licenseStatus,
		const char *	xmlRegInfo
	)

Contacts the SOAP server for a new license or a license refresh. NSLGetLicense must be called at least once after the library is initialized to maintain a license from the Nalpeiron daemon as it is responsible for starting and/or re-establishing the heartbeat to a Nalpeiron daemon. This function is deprecated use NSLObtainLicense instead.

Deprecated:: June 2020 This functions is deprecated and will be removed from a future version of the NSL library. Use NSLObtainLicense (NSLObtainLicense) instead

Parameters

authentication	Should be license code unless ABL is being used in which case the ABL username should be used. If authentication is non-NULL that number is used in the attempt to retrieve a license. If the authentication 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.
licenseStatus	on success contains the license status of the new license (see License status values).

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

int NSLGetLicenseCode ( char ** licenseCode )

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 NSLObtainLicense, NSLImportCertificate, etc.

Parameters

licenseCode contains the current license code. licenseCode should be freed with NSLFree.

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

int NSLGetLicenseInfo	(	uint32_t *	licenseType,
		uint32_t *	actType
	)

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

Parameters

licenseType	The type of license (ie trial, full, subscription, etc.) possible values are: (LICTYPE)
actType	The type of activation(ie online, offline, daemon, etc.) possible values are: (ACTTYPE)

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

int NSLGetLicenseStatus ( int32_t * licenseStatus )

Retrieves the status of the current license. Negative values indicate an invalid license state.

Parameters

licenseStatus contains the status value of the current license. (see License status values)

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

int NSLGetMaintExpDate ( char ** Date )

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

Parameters

Date	contains the data of the maintenance period expiration. If the maintenance period has expired the current date is retrieved. Date should be freed with NSLFree.

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

int NSLGetMaintExpSec	(	uint32_t *	sec,
		uint32_t *	expEpoch
	)

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.

Parameters

sec	on success contains the the number of seconds remaining in the current maintenance period.
expEpoch	if non-NULL, will contain the absolute expiration of the maintenance period in epoch seconds.

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

int NSLGetNumbAvailProc	(	uint32_t *	maxProc,
		uint32_t *	availProc
	)

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 function 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.

NB - inaccuracies can be produced when used in java apps, due to the way processes are counted in the jvm.

Parameters

maxProc	maximum number of processes allowed to run
availProc	number of processes still available.

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

int NSLGetPoolInfo	(	const char *	poolName,
		uint32_t *	poolMax,
		uint32_t *	poolAmt,
		int32_t *	poolStatus
	)

Get the number of pool elements current checked out along with the status of an element pool. NOTE this function replaces NSLGetPoolStatus (NSLGetPoolStatus).

Parameters

poolName	a NULL terminated, UTF-8 encoded string containing the five (5) character pool code of the pool to be drawn from.
poolMax	the maximum number of elements in the pool. If the caller does not have access to the pool, the return value will be 0.
poolAmt	the number of element checked out to current system.
poolStatus	the status of the pool (FEATSTATUS)

Returns: = 0 The call succeeded.; < 0 A negative error value is returned (Nalpeiron V10 error returns)

int NSLGetPoolStatus	(	const char *	poolName,
		uint32_t *	poolAmt,
		int32_t *	poolStatus
	)

Get the number of pool elements current checked out along with the status of an element pool. Function is deprecated use NSLGetPoolInfo (NSLGetPoolInfo) instead.

Deprecated:: June 2017 This functions is deprecated and will be removed from a future version of the NSL library.

Parameters

poolName	a NULL terminated, UTF-8 encoded string containing the five (5) character pool code of the pool to be drawn from.
poolAmt	the number of elements present on system
poolStatus	the status of the pool (FEATSTATUS)

Returns: >= 0 The call succeeded and the return value represents the total number of elements in the pool. If the caller does not have access to the pool, the return value will be 0.; < 0 A negative error value is returned (Nalpeiron V10 error returns)

int NSLGetSubExpDate ( char ** Date )

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

Parameters

Date	contains the data of the subscription period expiration. If the subscription period has expired the current date is retrieved. Date should be freed with NSLFree.

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

int NSLGetSubExpSec	(	uint32_t *	sec,
		uint32_t *	expEpoch
	)

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.

Parameters

sec	on success contains the the number of seconds remaining in the current subscription period.
expEpoch	if non-NULL, will contain the absolute expiration of the subscription in epoch seconds.

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

int NSLGetTimeStamp ( uint64_t * timeStamp )

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

Parameters

timeStamp contains seconds since epoch start. timeStamp should be freed with NSLFree.

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

int NSLGetTokenInfo	(	const char *	tokenName,
		uint32_t *	tokenMax,
		uint32_t *	tokenAmt,
		int32_t *	tokenStatus
	)

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

Parameters

tokenName	a NULL terminated, UTF-8 encoded string containing the five (5) character code of the token pool to be drawn from.
tokenMax	the maximum number of tokens in the pool. If the caller does not have access to the pool, the return value will be 0.
tokenAmt	the number of unconsumed tokens checked out to the current system.
tokenStatus	the status of the token pool (FEATSTATUS)

Returns: = 0 The call succeeded.; < 0 A negative error value is returned (Nalpeiron V10 error returns)

int NSLGetTrialExpDate ( char ** Date )

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

Parameters

Date	contains the data of the trial period expiration. If the trial period has expired the current date is retrieved. Date should be freed with NSLFree.

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

int NSLGetTrialExpSec	(	uint32_t *	sec,
		uint32_t *	expEpoch
	)

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.

Parameters

sec	on success contains the the number of seconds remaining in the current trial.
expEpoch	if non-NULL, will contain the absolute expiration of the trial in epoch seconds.

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

int NSLGetUDFValue	(	const char *	udfName,
		char **	udfValue
	)

Retrieve the value of a UDF (AA)

Parameters

udfName	a NULL terminated, UTF-8 encoded string containing the User Defined Field Name of the value to be accessed
udfValue	a NULL terminated UTF-8 encoded string associated with the User Defined Field Name's value. udfValue should be freed with NSLFree

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

int NSLGetVersion ( char ** version )

Gets the version of the NSL library being accessed.

Parameters

version on success contains the current version of the. version should be freed with NSLFree.

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

int NSLGetVMInfo	(	uint32_t *	isVM,
		char **	vmType
	)

Retrieves the virtual machine information about the system.

Parameters

isVM	a boolean valued interger indicating if the system is a virtual machine (1 for yes) or not (0 for no).
vmType	The type of virtual machine (ie KVM, Xen, HyperV, etc). Possible values are: (Virtual machine types). vmType should be freed with NSLFree.

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

Attention: See special information about Windows HyperV and HVCI (HyperV and HVCI)

int NSLImportCertificate	(	const char *	authentication,
		int32_t *	licenseStatus,
		char *	certContainer
	)

Imports a license from the given certificate.

Parameters

authentication	the license number or username(ABL) associated with the given license certificate
licenseStatus	contains the license status of the imported license license (see License status values).
certContainer	Either the certificate itself passed in as a NULL terminated string or the full path to a file containing the certificate. NOTE There are two special cases for the certContainer value: Case 1: If the certContainer is NULL the call will return 0 indicating that the library has NOT generated an activation request or 1 indicating that an activation request is pending and the library is awaitin a certificat import. Case 2: The keyword "clear" may be passed as a NULL terminated character 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: = 0 If the call succeeded; < 0 A negative error value is returned (Nalpeiron V10 error returns); = 1 and certContainer == NULL offline activation is under way.

int NSLObtainLicense	(	const char *	authentication,
		int32_t *	licenseStatus,
		const char *	xmlRegInfo,
		const char *	specialID
	)

Contacts the SOAP server for a new license or a license refresh. NSLObtainLicense must be called at least once after the library is initialized to maintain a license from the Nalpeiron daemon as it is responsible for starting and/or re-establishing the heartbeat to a Nalpeiron daemon.

Parameters

authentication	Should be license code unless ABL is being used in which case the ABL username should be used. If authentication is non-NULL that number is used in the attempt to retrieve a license. If the authentication is NULL, the function attempts to retrieve a trial license.
licenseStatus	on success contains the license status of the new license (see License status values).
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 utf8 system identifier. If specified, Nalpeiron server will include this value inside an application agility field called $SpecialID which can be accessed by the calling program via NSLGetUDFValue (NSLGetUDFValue). If this value has been specified before (ie in a previous call to NSLObtainLicense, for instance) the same value must be specified when requesting the license in the future else the request will be rejected by the Nalpeiron server. Once set, the value may be cleared by returning the license.

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

int NSLReadSecStore	(	const char *	rawKey,
		const char *	storeName,
		char **	storeValue
	)

Retrieve information contained in a secure storage area.

Parameters

rawKey	a NULL terminated, binary string containing no NULL values. The rawKey will be used to generate a suitable encryption key. This value should match the rawKey value passed to NSLWriteSecStore when the storage was created.
storeName	a UTF-8 encoded string containing the five (5) character UDF code of the value to be accessed. This storeName must match the name of the feature as created on the Nalpeiron server.
storeValue	binary string of length containing the information stored in storeName. The max size of the stored information is 4k. NOTE the contants of this value may be binary information. storeValue should be freed with NSLFree

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

int NSLRemoteCall	(	const char *	rpcName,
		char **	rpcReturn,
			...
	)

Call a remote proceedure at the Nalpeiron server. The parameters of this function begin with the remote proceedure's name (rpcName). The elipses represent the parameters for the remote function call. This argument list may be thought of as varName1, var1, varName2, var2, ... varNamen, varn, (char *)NULL. This list of arguments MUST be terminated with a null pointer and the null pointer must be cast to a char *. As many name/value pairs as needed may be passed into the function.

Parameters

rpcName	a NULL terminated, UTF-8 encoded string containing the name of the remote proceedure to be accessed.
rpcReturn	on success contains the return information from the rpc as a NULL terminated, UTF-8 encoded string. This may be NULL if no return is to be received from the call.
...	A sequence of NULL terminated UTF-8 encoded string pairs containing first the name of the variable then the contents of the variable ie varName1, var1, varName2, var2, ... ,(char )NULL. The sequence MUST end with a NULL pointer cast to a char .

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

int NSLRemoteCallV	(	const char *	rpcName,
		char **	rpcReturn,
		char **	rpcVarNames,
		char **	rpcVarVals
	)

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 NULL terminated, UTF-8 encoded string containing the name of the remote proceedure to be accessed.
rpcReturn	on success contains the return information from the rpc as a NULL terminated, UTF-8 encoded string. This may be NULL if no return is to be received from the call.
rpcVarNames	an array of pointers to NULL terminated, UTF-8 encoded strings listing the names of the variable to be passed to the RPC. The order of the names in this array MUST match the order of the values in rpcVarVals. The final entry of this array MUST be a NULL pointer.
rpcVarVals	an array of pointers to NULL terminated, UTF-8 encoded strings listing the values of the variables to be passed to the RPC. The order of the values in this array MUST match the order of the names in rpcVarNames. The final entry of this array MUST be a NULL pointer

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

int NSLRequestActivationCert	(	const char *	authentication,
		const char *	xmlRegInfo,
		const char *	specialID,
		char **	cert
	)

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

authentication	the license number or username (ABL) to be used in creating the certificate request. If the licenseNo is NULL and licensing is NOT ABL, 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 utf8 system identifier. If specified, Nalpeiron server will include this value inside an application agility field called $SpecialID which can be accessed by the calling program via NSLGetUDFValue (NSLGetUDFValue). If this value has been specified before (ie in a previous call to NSLRequestActivationCert) the same value must be specified when requesting the license in the future else the request will be rejected by the Nalpeiron server. Once set, the value may be cleared by offline deactivation.
cert	on success the resulting certificate request will be passed back in this parameter as a NULL terminated string. cert should be freed with NSLFree.

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

int NSLReturnFeature	(	const char *	featureName,
		const char *	authentication
	)

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

Parameters

featureName	a NULL terminated, UTF-8 encoded string containing the five (5) character feature code of the feature to be checked out.
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLReturnLicense	(	const char *	authentication,
		int32_t *	licenseStatus
	)

Returns the current license to the Nalpeiron server.

Parameters

authentication	The license code or username (ABL) associated with the current license
licenseStatus	contains the license status of the returned license (see License status values).

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

int NSLReturnPool	(	const char *	poolName,
		uint32_t	poolAmt,
		const char *	authentication
	)

Returns a specified number of elements to an element pool.

Parameters

poolName	a NULL terminated, UTF-8 encoded 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
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLReturnTokens	(	const char *	poolName,
		uint32_t	poolAmt,
		const char *	authentication
	)

Returns a specified number of unconsumed tokens to an token pool.

Parameters

poolName	a NULL terminated, UTF-8 encoded string containing the five (5) character pool code of the pool to be drawn from.
poolAmt	the number of tokens to return to the pool
authentication	the license number or username (ABL) of the current, valid system license

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

int NSLSetCredentials	(	const char *	username,
		const char *	password,
		USERAUTH	userAuthenticator,
		uint32_t	inDataSize,
		void *	inData
	)

Set username and password in the Nalpeiron library for future logins to the Nalpeiron licensing server or for a user provided authentication callback function. The credentials must already exist on the Nalpeiron server or the user provided authentication system.

The Nalpeiron library provides three forms of authentication. In the simplest form, the username and password are presented to NSLSetCredentials. Both are passed to Nalpeiron (the password is never stored or transmitted as plain text) for validation. If the Nalpeiron server validates them a license can be obtains via calls such as NSLObtainLicense.

In a second method, in addition to the username a callback function is passed into NSLCredentials. When authentication is required (ie when NSLSetCredentials is called but also when functions such as NSLObtainLicense and NSLGetActivationCertReq are called) the callback will be called from the library. The callback must have the following function prototype:

int64_t (*userAuthenticator)(char *uname, char *pword,
            void *inData, * char **authToken, uint32_t *outDataSize,
            void **outData);

where uname = username, pword = password, inData = arbitrary data passed to the callback via the library if inData was set via NSLSetCredentials (can be NULL), authToken = an authentication token that may be passed back to the library, unused in straight callback authentication. outData = arbitrary data that may be passed back to the library from the callback (available via NSLGetCredentials). outDataSize = the size in bytes of the outData.

If the return from the callback is >= 0, the library will assume that authentication has succeeded. If the return is < 0, the library will assume that authentication has failed. The return value of the callback is available via NSLGetCredentials.

In the third method of authentication the callback provides not just a return value but also an authentication token. The authentication token is passed to Nalpeiron for all licensing requests and will be verified there before the licensing occurs. One method of using the authentication token would be to generate a random string for the token during the callback. Before returning this string to the library, Nalpeiron web services would be used to push to Nalpeiron.

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. The username size is limited to 4k (4096 bytes).
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. The password size is limited to 4k (4096 bytes).
userAuthenticator	if NULL then authentication will take place at Nalpeiron. If non-NULL then the pointer will be used as a user supplied callback with the form: int64_t (userAuthenticator)(char uname, char pword, void inData, char *authToken, uint32_t outDataSize, void **outData);

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). The callback is called immediately (ie in NSLSetCredentials) and again whenever a call to NSLObtainLicense is made. In addition to checking the credentials the Nalpeiron server also checks the return value of the callback. A negative return value (<0) is considered a failure and the Nalpeiron server will refuse authentication.

Parameters

inDataSize	the size of the inData pointed to by inData. The maximum allowable size is 4k (4096 bytes).
inData	an optional bit of inData that, if non-NULL, will be passed into the userAuthenticator function. A copy of this inData is made and stored in memory by the library. inData is NOT stored on disk at any time which means it is lost when the library is closed. NOTE inData is neither used nor stored if a callback is not specified.

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

int NSLSetCredentialsSSO	(	const unsigned char *	ssoToken,
		uint64_t *	ssoExpEpoch,
		char *	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.
ssoExpEpoch	will contain the expiration date of the ssoToken in epoch seconds (number of seconds since midnight Jan 1 1970). This value will always be returned initially when the token is passed into the function. The expiration date of an existing token will be returned if ssoToken = NULL.
inData	can be used for one thing at this time, to override the JWT username with a specified username for ABL login. The format is a NULL terminated string consisting of ABLUSER:username. Otherwise, it should be set to NULL by the caller. Other uses may be added in the future.

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

Note: This function is currently in beta and may change in the future.; As part of the SSO retrieval of a license from Nalpeiron, an OpenID JWT is provided to the library. During the validation of this JWT, the library must contact the IDP responsible for authentication using TLS. Validating the TLS connection requires a valid certificate bundle to be present and available on the end user's system. The library will use the standard methods of accessing this bundle, should they fail you may place your own certificate bundle in the library's WorkDir. Generally, such a failure is caused by an invalid or non-standard certificate bundle and will be indicated by a -4460 return from the NSLSetCredentialsSSO call.; If you encounter such a situation you may provide the library with at cert bundle. This feature must be enabled when you create the library by checking the "custom certificate bundle" checkbox. The bundle should be place in the library's WorkDir and name in the same manner as the other files there but with a .pem extension. For instance, if you license file is ce41f5a106b7dc878f.lic then the certicate bundle should be ce41f5a106b7dc878f.pem. With this option enabled and the cert bundle in place, if the library fails to validate the TLS connection with the system's certificates, it will fall back on the certs you provide in the WorkDir.

int NSLTestConnection ( )

Tests the network connection to Nalpeiron.

Deprecated:: June 2018 This function is deprecated and will be removed from a future version of the NSL library. Use NSLTestConnection2 (TestConnection2) instead

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

int NSLTestConnection2	(	uint32_t	connTimeOut,
		uint32_t	transTimeOut
	)

Tests the network connection to Nalpeiron.

Parameters

connTimeOut	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.
transTimeOut	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)

int NSLValidateLibrary	(	uint32_t	custID,
		uint32_t	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)

int NSLWriteSecStore	(	uint32_t	storeSize,
		const char *	rawKey,
		const char *	storeName,
		const char *	storeValue
	)

Store information in a secure storage area.

Parameters

storeSize	should contain the length of the binary to be stored in storeValue. If your stored string contains a NULL terminator that NULL byte must be included in the size.
rawKey	a NULL terminated binary string containing no other NULL values. This value will be used to generated a suitable encryption key. This value must be passed to NSLWriteSecStore when the storage is retrieved.
storeName	a UTF-8 encoded string containing the five (5) character UDF code of the value to be accessed. This storeName must match the name of the feature as created on the Nalpeiron server.
storeValue	binary string of length storeSize containing the information stored in storeName. The max size of the stored information is 4k. NOTE the contants of this value is treated as a binary string. If you wish a NULL terminator it must be included in the string when it is stored. storeValue should be freed with NSLFree

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

Files

Functions

Detailed Description

Function Documentation