 |
Zentitle SDK and Library
|
|
Zentitle SDK and Library
|
Files | |
| file | shaferH.h |
| Generic Nalpeiron V10 library functions. | |
Functions | |
| int | PSLLibOpen (const char *xmlParams) |
| Opens and initializes the Nalpeiron Passive licensing library. PSLLibOpen takes an UTF-8 XML string as a parameter to ensure that future library updates retain backward compatibility. More... | |
| int | PSLLibClose () |
| 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. More... | |
| int | PSLGetErrorMsg (int nalpErrorNo, char **errorMsg) |
| Get a descriptive string for nalpeiron error codes. More... | |
| int | PSLGetFilepath (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. More... | |
| int | PSLValidateLibrary (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 | PSLGetVersion (char **version) |
| Gets the version of the Passive licensing library being accessed. More... | |
| int | PSLGetLibraryOptions (uint64_t *libOptions) |
| Retrieves information about the choices used at library creation. More... | |
| int | PSLGetComputerID (char **computerID) |
| Gets the computer ID of the current system. More... | |
| int | PSLImportLicense (const char *licenseCode, int32_t *licenseStatus, char *licContainer) |
| Import a license. More... | |
| int | PSLGetLeaseExpSec (uint32_t *seconds, 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 | PSLGetLeaseExpDate (char **date) |
| Retrieves the expiration of the license as a time/date string (Wed Jul 17 19:59:12 2013, for example). More... | |
| int | PSLGetMaintExpSec (uint32_t *seconds, 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 | PSLGetMaintExpDate (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 | PSLGetLicenseStatus (int32_t *licenseStatus) |
| Retrieves the status of the current license. Negative values indicate an invalid license state. Possible values: More... | |
| int | PSLGetLicenseCode (char **licenseCode) |
| Retrieves the license code used with the current license. More... | |
| int | PSLGetNumbAvailProc (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 | PSLGetFeatureStatus (const char *featureName, int32_t *featureStatus) |
| Checks the current license for the status of featureName. Status if returned in featureStatus. More... | |
| int | PSLGetUDFValue (const char *udfName, char **udfValue) |
| Retrieve the value of a UDF (AA) More... | |
| int | PSLFree (void *memptr) |
| The PSLFree functions is available to free any memory allocated by the PSL 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 PSL library. This function is provided to ensure that memory allocated from the PSL heap is freed there. PSLFree should be used on the memory returned from the PSL library. More... | |
| int PSLFree | ( | void * | memptr | ) |
The PSLFree functions is available to free any memory allocated by the PSL 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 PSL library. This function is provided to ensure that memory allocated from the PSL heap is freed there. PSLFree should be used on the memory returned from the PSL library.
| memptr | a pointer to the memory to be freed. |
| int PSLGetComputerID | ( | char ** | computerID | ) |
Gets the computer ID of the current system.
| computerID | on success contains the computer ID of the current system. computerID should be freed with PSLFree. |
| int PSLGetErrorMsg | ( | int | nalpErrorNo, |
| char ** | errorMsg | ||
| ) |
Get a descriptive string for nalpeiron error codes.
| nalpErrorNo | is a negative return value from one of the Nalpeiron functions |
| errorMsg | is a descriptive string explaining that error. errorMsg should be freed with NSLFree/NSAFree by the caller. |
| int PSLGetFeatureStatus | ( | const char * | featureName, |
| int32_t * | featureStatus | ||
| ) |
Checks the current license for the status of featureName. Status if returned in featureStatus.
| 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 (Feature status values) |
| int PSLGetFilepath | ( | 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.
| extension | A string indicating the extension to be used on the filepath. Common examples would be .lic, .cache, .sinfo, etc. |
| filepath | should be freed with NSLFree/NSAFree by the caller. |
| int PSLGetLeaseExpDate | ( | char ** | date | ) |
Retrieves the expiration of the license as a time/date string (Wed Jul 17 19:59:12 2013, for example).
| date | contains the data of the license expiration. If the license has expired the current date is retrieved. Date should be freed with PSLFree. |
| int PSLGetLeaseExpSec | ( | uint32_t * | seconds, |
| 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.
| seconds | 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. |
| int PSLGetLibraryOptions | ( | uint64_t * | libOptions | ) |
Retrieves information about the choices used at library creation.
| libOptions | a bit field consisting of on/off information for library creation options |
| int PSLGetLicenseCode | ( | char ** | licenseCode | ) |
Retrieves the license code used with the current license.
| licenseCode | contains the current license code. licenseCode should be freed with PSLFree. |
| int PSLGetLicenseStatus | ( | int32_t * | licenseStatus | ) |
Retrieves the status of the current license. Negative values indicate an invalid license state. Possible values:
| licenseStatus | contains the status value of the current license. (see License status values) |
| int PSLGetMaintExpDate | ( | char ** | date | ) |
Retrieves the expiration of the maintenance period as a time/date string (Wed Jul 17 19:59:12 2013, for example).
| 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 PSLFree. |
| int PSLGetMaintExpSec | ( | uint32_t * | seconds, |
| 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.
| seconds | 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. |
| int PSLGetNumbAvailProc | ( | 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 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.
| maxProc | maximum number of processes allowed to run |
| availProc | number of processes still available. |
| int PSLGetUDFValue | ( | const char * | udfName, |
| char ** | udfValue | ||
| ) |
Retrieve the value of a UDF (AA)
| 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 udfName. udfValue should be freed with PSLFree |
| int PSLGetVersion | ( | char ** | version | ) |
Gets the version of the Passive licensing library being accessed.
| version | on success contains the current version of the. version should be freed with PSLFree. |
| int PSLImportLicense | ( | const char * | licenseCode, |
| int32_t * | licenseStatus, | ||
| char * | licContainer | ||
| ) |
Import a license.
| licenseCode | contains the current license code. licenseCode should be freed with PSLFree. |
| licenseStatus | contains the status value of the current license. (see License status values) |
| licContainer | Either the license itself passed in as a NULL terminated string or the full path to a file containing the license. |
| int PSLLibClose | ( | ) |
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.
| int PSLLibOpen | ( | const char * | xmlParams | ) |
Opens and initializes the Nalpeiron Passive licensing library. PSLLibOpen takes an UTF-8 XML string as a parameter to ensure that future library updates retain backward compatibility.
| xmlParams | string of the form: <?xml version=\"1.0\" encoding=\"UTF-8\"?> <PSLXMLParams> <SecurityValue>value</SecurityValue> <LicenseCode>value</LicenseCode> <LogLevel>value</LogLevel> <WorkGroup>group</WorkGroup> <MaxLogSize>int</MaxLogSize> <WorkDir>dir_path</WorkDir> <LogQLen>int</LogQLen> <WinSysTO>uint32_t<WinSysTO> </PSLXMLParams> |
where:
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).
LicenseCode is the "client id" you associated with the machine during license code creation. If this value is not supplied then library initialization will fail.
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, or 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.
WinSysTO - Timeout value in milliseconds for Windows system call. Valid range is 0 (use default library value of 5s) to 180000 ms (3min). You should NOT change the value from the default unless you regularly experience timeout error returns from the library's initialization routines. NOTE the Windows system calls are blocking. If you institute a timeout of, say, 2 min then the call may well block the library's return for the full 2 min.
| int PSLValidateLibrary | ( | 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.
| 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. |
1.8.9.1
