 |
Zentitle SDK and Library
|
|
Zentitle SDK and Library
|
Files | |
| file | shaferH.h |
| Generic Nalpeiron V10 library functions. | |
Functions | |
| int | NalpLibOpen (const char *xmlParams) |
| Opens and initializes the Nalpeiron V10 library. NalpLibOpen takes an UTF-8 XML string as a parameter to ensure that future library updates retain backward compatibility. More... | |
| 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. More... | |
| int | NalpGetErrorMsg (int nalpErrorNo, char **errorMsg) |
| Get a descriptive string for nalpeiron error codes. More... | |
| 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. More... | |
General library functions from Nalpeiron V10
| int NalpGetErrorMsg | ( | 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 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.
| 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 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.
| int NalpLibOpen | ( | const char * | xmlParams | ) |
Opens and initializes the Nalpeiron V10 library. NalpLibOpen 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\"?> <SHAFERXMLParams> <NSLEnabled>1</NSLEnabled> <NSAEnabled>1</NSAEnabled> <HTTPSEnabled>1</HTTPSEnabled> <SecurityValue>value</SecurityValue> <OfflineMode>0 or 1</OfflineMode> <LogLevel>value</LogLevel> <WorkGroup>group</WorkGroup> <MaxLogSize>int</MaxLogSize> <WorkDir>dir_path</WorkDir> <LicenseCode>value</LicenseCode> <LogQLen>int</LogQLen> <CacheQLen>int</CacheQLen> <SoapThreadsMin>int/</SoapThreadsMin> <SoapThreadsMax>int</SoapThreadsMax> <ClientHostname>optional hostname</ClientHostname> <OfflineMode>0 or 1</OfflineMode> <ProxyIP>IP addr</ProxyIP> <ProxyPort>port number</ProxyPort> <ProxyUsername>string</ProxyUsername> <ProxyPassword>string</ProxyPassword> <NSLConnTO>uint32_t</NSLConnTO> <NSLTransTO>uint32_t</NSLTransTO> <NSAConnTO>uint32_t</NSAConnTO> <NSATransTO>uint32_t</NSATransTO> <WinSysTO>uint32_t</WinSysTO> <DaemonIP/> <DaemonPort/> <DaemonUser>/ <DaemonPass/> </SHAFERXMLParams> |
where:
NSLEnabled enables the NSL library when set to 1 and disables the NSL library when set to 0.
NSAEnabled enables the NSA library when set to 1 and disables the NSA library when set to 0.
HTTPSEnabled enables https for the library licensing and analytics transactions with the Nalpeiron server. HTTP is the default. NOTE: If HTTPS was enabled when creating the library then the HTTPSEnabled tag will have no affect on the library. It will always use https. However, if the library was created without https enabled then this tag will enable https when used during NalpLibOpen.
SecurityValue is used by NSL library only. 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 a log file reaches this size, a new log file is created up to a maximum of 5 log files. When there are 5 full log files, the oldest one is deleted and a new one is created. 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).
LicenseCode is a passive license "client ID" and is required when importing a passive license. The passive license code is used ONLY when importing a passive license file into the NSL library.
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 - Used only by the NSA library. Network connections between the NSA library and the Nalpeiron server are handled by a lthread pool.
ClientHostname - An optional tag. If used the contents of the tag will be used in diplays on the Nalpeiron daemon. This tag provides a user friendly ID for displays.
OfflineMode Used only by the NSA library. See NSA.USAGE for details.
ProxyIP/ProxyPort - If the 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. IPv6 addresses should be enclosed in square brackets as
<ProxyIP>[fdb9:d12:77a8:8a::1d2]</ProxyIP>
ProxyUsername/ProxyPassword - If you are using a network proxy to which requires a username and password, specify them here.
NSLConnTO/NSAConnTO - Timeout value in milliseconds for the connection portion of any communication with the Nalpeiron server or daemon. If unspecified or 0 the default value of 30 seconds is used.
NSLTransTO/NSATransTO - Timeout value in milliseconds for the entire transaction between the Nalpeiron client library and the Nalpeiron server or daemon. This includes the time for name resolution, connection, etc. If unspecified or 0 the default value of 30 seconds is used.
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.
DaemonIP/DaemonPort - Used only in the case that the client library is contacting a local Nalpeiron server. See daemon documentation for further info. IPv6 addresses should be enclosed in square brackets as
<DaemonIP>[fdb9:d12:77a8:8a::1d2]</DaemonIP>
DaemonUsername/DaemonPass - Used only in the case that the client library is contacting a local Nalpeiron daemon. The supplied credentials will be those used to access the daemon.
1.8.9.1
