Page tree
Skip to end of metadata
Go to start of metadata

Library Usage

 

All functions return positive numbers (or 0) on success and negative number on error. Strings passed into NSL are expected to be either ANSI C strings or UTF8 encoded unicode.

The following functions are provided by the NSL library. Of course, as you will be accessing them from the shared libraries rather than directly you need to use the typedeffed functions pointers (see  NalpeironNSL.h in the c/c++ codekit) rather than these prototypes. For example usage see nslExample.c in the code kit.

 

Current Version: 3.2.60.0

 

 

 

int NalpLibOpen ( const char *xmlParams);

Opens and initializes the library. Returns 0 for success and a negative number for an error. The NSAOpen takes its parameters in the form of a xml string. This ensures any future changes to NSAOpen will remain backward compatible. The current form of the xml string is:

<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<SHAFERXMLParams>
<NSLEnabled>1</NSLEnabled>
<NSLEnabled>1</NSLEnabled>
<SecurityValue>value</SecurityValue>
<OfflineMode>0 or 1</OfflineMode>
<LogLevel>value</LogLevel>
<WorkGroup>group</WorkGroup>
<MaxLogSize>int</MaxLogSize>
<WorkDir>dir_path</WorkDir>
<LogQLen>int</LogQLen>
<CacheQLen>int</CacheQLen>
<SoapThreadsMin>int/</SoapThreadsMin>
<SoapThreadsMax>int</SoapThreadsMax>
<OfflineMode>0 or 1</OfflineMode>
<ProxyIP>IP addr</ProxyIP>
<ProxyPort>port number</ProxyPort>
<ProxyUsername>string</ProxyUsername>
<ProxyPassword>string</ProxyPassword>
<DaemonIP/>
<DaemonPort/> 
<DaemonUser>/ 
<DaemonPass/> 
</SHAFERXMLParams> 

 

where:

 

NSAEnabled enables the NSA library when set to 1 and disables the NSA library when set to 0.

NSLEnabled enables the NSL library when set to 1 and disables the NSA library when set to 0.

SecurityValue is a random number in the range 1 to 500 inclusive. The security values is used along with the authentication values stamped into the library to create a unique offset that is added to all returns.  The default is 0 (ie returns from the library will NOT be modified).

LogLevel is an integer 0 to 6. If loglevel is not specified it will default to level 0 (off). You should not use log level higher than 4.  The higher levels do not provide any useful end user debugging.

0 logging off
1 errors only
2 errors and warnings
3 errors, warnings, and informational messages
4 errors, warnings, info and debug
5 and 6 are for Nalpeiron internal use

WorkGroup the working group for the license files, log files, etc on Unix and Unix-like systems.  On Windows systems the you should set the ownership and pemissions on the containing folder during installation.  These permissions/ownerships will then be inherited by the files upon creation.  If WorkGroup is empty the system defaults will be used. That is, the permissions on the files we create are set by the default umask setting of the system (usually 0666 for files and 002 on Linux and 022 on OSX).  If the WorkGroup is set, the files are owned by this group and the umask set to 002.  NOTE the group must exist or an error will result.A special group is "nalpworld". If the WorkGroup is set to nalpworld the umask is set to 0 allowing universal access to the files.

On most *nix systems, the calling process (ie the process that is using the Nalpeiron library) must have CAP_SETGID capability.  Often, a give process will not have this capability for security reasons which in turns means the library will NOT be able to change its group and thus the group of the files it opens.  To work around this issue set the gid on the work directory to the group you want to own the files in it.  That is,

chmod g+s your/WorkDir

chgrp groupname your/WorkDir

or, for WorkDir = /tmp/workdir and workgroup = testgroup

chmod g+s /tmp/workdir

chgrp testgroup /tmp/workdir

This coupled with setting the <WorkGroup> tag will ensure that all files and subdirectories are created with correct group ownership. The setgid on the workdir will ensure the proper group ownership and the <WorkGroup> tag will ensure the umask is set correctly.

MaxLogSize is the maximum length of the log file on disk in bytes. When the log file reaches this size it is truncated to zero length. The default value is 0 (ie unlimited growth allowed). it is truncated to zero length.  The default value is 0 (ie unlimited growth allowed).  

WorkDir is the location where NSL will store all its working files (ie log file, cache file, license files, etc).  If this value is not specified the files will be stored in the default Nalpeiron directory (cwd (current working directory) on Linux and Mac, in a publically accessible directory selected by the OS on Windows).

LogQLen is the maximum length of the log queue.

CacheQLen is the maximum length of the cache queue.  Used only by the NSA library.  See NSA.USAGE for more details.

SoapThreadsMin/SoapThreadsMax  - Network connections between the NSA library and the Nalpeiron server are handled by a lthread pool.

OfflineMode Used only by the NSA library.  See NSA.USAGE for details.

ProxyIP/ProxyPort - If the NSA library is connecting to the internet via a proxy use these values to specify the IP address and port
number of the proxy server.  If no proxy is used, they can be left empty or completely unspecified.  The default is no proxy.

ProxyUsername/ProxyPassword - If you are using a network proxy to which requires a username and password, specify them here.

OfflineMode - Used only by the NSA library.  See NSA.USAGE for details.

DaemonIP/DaemonPort - Used only in the case that the client library is contacting a local Nalpeiron server.  See daemon documentation for further info.

DaemonUsername/DaemonPass - Used only in the case that the client library is contacting a local Nalpeiron server.  See daemon documentation for further info 

int NalpLibClose() Shuts down the library. THIS FUNCTION MUST BE CALLED IMMEDIATELY BEFORE CLOSING THE LIBRARY (ie with dlclose). If this function is not called before the library is closed, information may be lost and memory corruption could occur.

Returns 0 for success and a negative number for an error.
int NalpGetErrorMsg(int nalpErrorNo, char **errMsg) Get a descriptive string for nalpeiron error codes. nalpErrorno is a negative return value from one of the Nalpeiron functions and errorMsg is a descriptive string explaining that error. errorMsg should be freed with NSLFree by the caller.
int NalpGetFilepath(const char *extension, char **filepath); 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.

int NSLValidateLibrary(uint32_t customerID, uint32_t productID);

Verifies that the shared library you are accessing is the library you stamped. It does this by checking the customerID and productID sent in against the stamped values. If they match, 0 (zero) is returned.  On mismatch, a negative error value is returned.

int NSLGetVersion(char **version);

Returns the version of the NSL library being accessed.  version should be freed with NSLFree.

int NSLGetComputerID(char **computerID);

Returns the computer ID of the current system.  computerID should be freed with NSLFree.

int NSLGetHostName(char **hostname);

Returns the name of the SOAP server the library contacts for licensing information.  Hostname should be freed with NSLFree.

int NSLTestConnection();

To be released in V2.1.109.  Tests connection to Nalpeiron.  Used only for testing the library and connectivity.  Returns 0 on success and a negative number for an error. retBuf should be freed with NSLFree.

int NSLGetLeaseExpSec(uint32_t *sec, uint32_t *epochDate);

Retrieves the number of epoch seconds (seconds from Jan 1 1970) until the license 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 returned.

int NSLGetLeaseExpDate(char **date);

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

 int NSLGetTrialExpSec(uint32_t *sec, uint32_t *epochDate);

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

int NSLGetTrialExpDate(char **date);

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

int NSLGetMaintExpSec(uint32_t *sec, uint32_t *epochDate); 

Retrieves the number of seconds until the subscription expiration.  Note that the number of seconds is an unsigned int.  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 returned.

int NSLGetMaintExpDate(char **date);

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

int NSLGetSubExpSec(uint32_t *sec, uint32_t *epochDate);

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

int NSLGetSubExpDate(char **date);

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

int NSLGetLicenseStatus(int32_t *licenseStatus);

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

     16    Daemon Master License

     15    Daemon LTCO License

     14    Daemon OEM License

     3 Concurrent License Activated

     2 Trial Activated

     1 Product Authorized

     -1 Product Expired

     -2 Computer backdated too many times

     -3 Feature not Authorised

     -4 Feature/Product not Found

     -5 License doesn't verify

     -6 Returned license to server

     -7 Date set back too far

     -8  Product in Invalid State

     -50 No Available Licenses

     -51 Daemon Failed to Verify

     -52 Daemon System ID Failure

     -110 Product is InActive

     -111 Invalid Trial Period     

     -112 ComputerID has already been activated

     -113 Trial Expired

     -114 LicenseCode is inactive

     -115 Number of Allowed Activations Exceeded

     -116 Subscription Expired

     -117 Duplicate Device ID

     -200 Too Many Heartbeats Missed (Network)

     -201 Seat Revoked By Daemon

int NSLGetLicenseCode(char **licenseCode);

Retrieves the license code used with the current license. licenseCode should be freed with NSLFree.

int NSLGetTimeStamp(uint64_t *timeStamp);

Returns the current time (seconds since epoch start) from the Nalpeiron daemon.

int NSLGetLicense(const char *licenseNo, int32_t *licenseStatus, const char *xmlRegInfo);

Contacts the SOAP server for a new license.  The status of the new license is returned in licenseStatus.  If licenseNo is non- NULL that number is used in the attempt to retrieve a license. If the licenseNo is NULL, the function attempts to retrieve a trial license.  Registration information may be passed to the Nalpeiron server using the xmlRegInfo string.  If there is no registration information, this pointer should be NULL.

  int NSLReturnLicense(const char *licenseNo, int32_t *licenseStatus);

Returns the current license to the Nalpeiron server.

  int NSLImportCertificate(const char *licenseNo, int32_t *licenseStatus, const char *cert);

Imports a license from the certificate pointed to.  Inputs are licenseNo and cert, licenseStatus is returned.

  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 is the type of virtual machine (i.e. KVM, Xen, HyperV, etc). Possible values are: (Virtual machine types). vmType should be freed with NSLFree. Returns: 0 if the call succeeded, less than 0 a negative error value is returned (Nalpeiron V10 error returns.)

int NSLGetActivationCertReq(const char *licenseNo, const char *xmlRegInfo, char **cert);

Generate an request for a activation certificate from the Nalpeiron server.  The request can be emailed or otherwise sent to Nalpeiron. 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 should be freed with NSLFree.

int NSLGetDeactivationCertReq(const char *licenseNo, char **cert);

Generate an request for a deactivation from the Nalpeiron server.  Note the current license is deactivated immediatedly when
the request is generated. The request can be emailed or otherwise sent to Nalpeiron. cert should be freed with NSLFree.

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

Checks the current license for the status of featureName. Status if returned in featureStatus.  Possible feature status codes:
 

1    Authorized

0    Unset

-1    Error

-2    Unknown Feature Requested

-3    Feature Request Denied

-4    Feature Not Authorized

-5    License Expired

 

int NSLGetLicenseInfo(uint32_t * licenseType, uint32_t * actType);

Returns the license type and activation type (actType.)

licenseType

0    Unknown

2    Trial

3    Permanent, node-locked

4    Permanent, concurrent

5    Subscription, node-locked

6    Subscription, concurrent

7    Network License

8    Subscription Network License

9    Daemon LTCO

10    Daemon OEM

11    Reserved for internal use

  actType

   0      Unknown
   1      License was activated online
   2,     License was activated with a certificate
   3      License was activated via daemon
   4      Reserved for internal use


int NSLGetUDFValue(const char *UDFName, char **UDFValue);

Gets the "value" associated with the UDF (User Defined Field) name. UDFValue should be freed with NSLFee.

int NSLGetNumbAvailProc(uint32_t *noProcs, 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 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.

int NSLCheckoutFeature(const char *featureName, int32_t *featureStatus, const char *licenseNo);

Checkout one use of a "floating feature".  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 usage was available.

int NSLReturnFeature(const char *featureName, const char *licenseNo);

Return a checked out floating feature to the server.

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

Checks a specified number of elements out of an element pool where

poolname: 5-digit pool code.

poolAmt: number of elements to be checked out.

licenseNo: license code.

int NSLReturnPool(const char *poolName,uint32_t poolAmt, const char *licenseNo);

Checks a specified number of elements into an element pool where  

 poolname: 5-digit pool code.

 poolAmt: number of elements to be checked in.

 licenseNo: license code.

int NSLGetPoolStatus(const char *poolName, uint32_t *poolAmt, int32_t *poolStatus); DEPRECATED by NSLGetPoolInfo


 Returns the pool status and number of elements checked out for a given element pool and license code where

poolname: 5-digit pool code.

poolAmt: number of elements checked out.

poolStatus: pool status code

Status values:

1    Authorize

0    Unset

-1    Error

-2    Unknown Feature Requested

-3    Feature Request Denied

-4    Feature Not Authorized

-5    License Expired

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.

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 elements to withdraw from the pool.

poolStatus: pool (feature) status code

Status values:

1 Authorize

0 Unset

-1 Error

-2 Unknown Feature Requested

-3 Feature Request Denied

-4 Feature Not Authorized

-5 License Expired

int NSLGetCounter(const char *counterName, uint64_t *count);

Soon to be released. Get a usage counter value.

int NSLIncrementUsage(const char *counterName, uint64_t *count);

Soon to be released. Increment the usage counter.

int NSLPutUDFValue(const char *UDFName, const char *UDFValue);

Soon to be released. If the UDF is writable, sets the "value" associated with it.

int NSLFree(void *memptr);

The NSAFree functions is available to free any memory allocated by the NSA 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.

 

 

 

 

 

 

 

 

  • No labels