General Overview
The NSA library provides an easy method of added analytics collection to your software. NSA can easily be added to new or existing software and it is a shared library and can be accessed as such. The library is intended to be used with the dlopen family of functions (dlopen, dlclose, dlsym, etc). While it may be possible to link to the NSA library it is not a currently supported option.
The NSA library is threaded. Major threads include the communication thread pool, the caching thread with queue and the logging thread with queue.
All access to the library MUST be started with a call to NalpLibOpen and ended with a call to NalpLibClose.
NalpLibOpen creates the threads and performs some general housekeeping. NalpLibClose issues shutdown orders and waits for the threads to complete what they are doing. The shutdown should not take long. The communication thread will complete any ongoing transaction then pass off the rest of its jobs to the caching thread. The caching thread will write out all the pending jobs to cache and then shut down.
Closing your program without issuing a NalpLibClose can result in data loss.
Installation
The NSA library is contained within the NSL library, and can be installed anywhere that is convenient.
Prevention of Data Loss:
To prevent data loss, the NSA library caches any information that hasn't been sent in the case of network interrupt, shutdown, or similar circumstances. The cache file is circular with a maximum size equal to the value you stamped into the library. The cache file grows and shrinks to the minimum size necessary to hold the cached data.
However, its maximum size is constrained by the size stamped into the NSA library. Once the maximum size has been reached, the cache file wraps around and begins overwriting the oldest data. When a successful connection to Nalpeiron is detected, the entire cache will be automatically sent.
Privacy
Nalpeiron has taken several steps to help our customers cope with the many privacy laws around the world. First, there is a privacy setting that can be stamped into the shared library then accessed and changed via NSA functions. Second, Nalpeiron provides geographical location information to the NSA library and incoming data is tagged by country. If incoming data originates in a region where it is illegal to collect such data, the incoming data is dropped and never stored.
The privacy setting (accessed with NSAGetPrivacy and NSASetPrivacy) is used to enable or disable all NSA functions that collect information. If this value is set (= 1), all such functions are disabled. If this value is not set (= 0), the functions are enabled though data may still not be collected due to local privacy laws. If the value has never been set (= 2), the privacy setting stamped into the library is used. The privacy setting is stored along with the cache file and, if that file is deleted, the privacy setting will be to. In this case, the setting defaults to the value stamped into the library until NSASetPrivacy is used.
Nalpeiron has provided privacy controls with the library so you can tailor your data collection to local laws.
Library Usage
Strings passed into NSA are expected to be either ANSI C strings or UTF8 encoded Unicode. The following functions are provided by the NSA 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 NalpeironNSA.h in the c/c++ SDK) rather than these prototypes. For example, usage see nsaExample.c in the SDK.
|
Function
|
Description
|
||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
int NalpLibOpen(const char *xmlParams)
|
Initializes the library. Returns 0 for success and a negative number for an error. NalpLibOpen's parameters (char *xmlParams) are passed in as a a UTF* character string containing valid XML of the following form:
<?xml version=\"1.0\" encoding=\"UTF-8\"?> <SHAFERXMLParams>
<NSAEnabled>1</NSAEnabled>
<NSLEnabled>1</NSAEnabled>
<SecurityValue>value</SecurityValue>
<WorkDir>dir_path</WorkDir>
<LicDir>dir_path</LicDir>
<WorkGroup>group</WorkGroup> <LogLevel>value</LogLevel>
<MaxLogSize>int</MaxLogSize> <LogDir>dir_path</LogDir> <LogQLen>int</LogQLen> <CacheQLen>int</CacheQLen> <SoapThreadsMin>int</SoapThreadsMin>
<SoapThreadsMax>int</SoapThreadsMax> <OfflineMode>0 or 1</OfflineMode> <ProxyIP>IP addr</ProxyIP> <ProxyPort>port number</ProxPort> <ProxyUsername>string</ProxUsername> <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. Default is disabled. NSLEnabled enables the NSL library when set to 1 and disables the NSL library when set to 0. Default is disabled. 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). 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). LicDir is the location of the license file. If not set, the license directory will bet the same as the WorkDir. WorkGroup the working group for the license files, log files, etc on Unix and Unix-like systems. On Windows systems, you should set the ownership and permissions on the containing folder during installation. These permissions/ownership will then be inherited by the files upon creation. logdir is the location where NSA will store its log file and cache file. If this value is not specified the files will be stored in the default Nalpeiron directory (/etc/nalpeiron on Linux and Mac, it a publicly accessible directory selected by the OS on Windows.) 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.
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 (i.e. unlimited growth allowed). LogQLen is the maximum length of the log queue. Once the logqueue reaches this length, additional log entries will be discarded. As messages in the queue are written to the log file, the queue will shrink and logging will automatically begin again. The default is 300. CacheQLen is the maximum length of the cache queue. Once the cache queue reaches this length, additional cache entries will be discarded. As messages in the queue are written to the cache file, the queue will shrink and caching will automatically begin again. The default is 25. SoapThreadsMin/SoapThreadsMax - Network connections between the NSA library and the Nalpeiron server are handled by a lthread pool. The values specify the minimum number of threads available to the pool and the maximum number of threads available to the pool. The number of threads in the pool will grow and shrink between these two extremes as needed. The default for each is 10. OfflineMode - If OfflineMode is on (1), the no data is sent to the Nalpeiron server. All transactions are written immediately to cache. The library makes no attempts to collection location information or send the cache to Nalpeiron. The default is 0 (i.e. on-line). 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. 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. Returns 0 for success and a negative number for an error. This function must be called immediately before closing the library (i.e. with dlclose). If this function is not called before the library is closed, information may be lost and memory corruption could occur.
|
||||||||||||||||||||||||||||||||||||||||
| 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 and errorMsg is a descriptive string explaining that error. errorMsg should be freed with 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. | ||||||||||||||||||||||||||||||||||||||||
| int NSATestConnection(const char *nsaClientData, uint32_t *transID) |
Connects to Nalpeiron and retrieves a "Hello World". Used only for testing the library and connectivity. Returns 0 on success and a negative number for an error. The parameter transID allows a series of transactions to be grouped together with a transaction ID. To retrieve a transaction ID from any function, set transID = 0 and call the function. Upon return, transID will be set with a random number that will be passed to the Nalpeiron server to identify the transaction. Send this value into any functions that are to be grouped together. This is particularly useful for function pairs such as NSALogin/NSALogout, NSAAppStart/NSAAppStop, NSAFeatureStart/NSAFeatureEnd, etc. If you do not wish to use the transaction ID a NULL pointer will disable it. |
||||||||||||||||||||||||||||||||||||||||
| int NSAGetPrivacy() | Checks current privacy settings. Returns 0 for "no privacy", 1 for "privacy enabled", 2 for "unset" and a negative number for an error. If privacy is unset, the privacy setting used will be the one stamped into the library. | ||||||||||||||||||||||||||||||||||||||||
|
int NSASetPrivacy(unsigned short setting) |
Sets a privacy value for the library. Possible values for setting are 0 "no privacy", 1 "privacy enabled" or a negative number for an error. | ||||||||||||||||||||||||||||||||||||||||
|
NSAAppStart(const char *username, const char *nsaClientData,uint32_t *transID) |
Records startup of your application. Returns 0 on success and a negative number for an error. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
NSAAppStop(const char *username, const char *nsaClientData, uint32_t *transID) |
Records shutdown of your application. Returns 0 on success and a negative number for an error. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSALogin(const char *username, const char *nsaClientData, uint32_t *transID) |
Records login of username. Returns 0 on success and a negative number for an error. Username should be a ANSI C string or a utf8 encoded unicode string. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSALogout(const char *username, const char *nsaClientData, uint32_t *transID); |
Records logout of username. Returns 0 on success and a negative number for an error. Username should be a ANSI C string or a utf8 encoded unicode string. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSAFeatureStart(const char *username, const char *featureCode, const char *nsaClientData, uint32_t *transID) |
Records start of use of featureCode by username. Returns 0 on success and a negative number for an error. Username and featureCode should be a ANSI C strings or a utf8 encoded unicode strings. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSAFeatureStop(const char *username, const char *featureCode, const char *nsaClientData, uint32_t *transID) |
Records end of use of featureCode by username. Returns 0 on success and a negative number for an error. Username and featureCode should be a ANSI C strings or a utf8 encoded unicode strings. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSAException(const char *username, const char *exceptionCode, const char *description, const char *nsaClientData, uint32_t *transID) |
Records an error of type exceptionCode by username with details in description. Returns 0 on success and a negative number for an error. Username, featureCode, and description should be a ANSI C strings or a utf8 encoded unicode strings. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSASysInfo(const char *username, const char *applang, const char *version, const char *edition, const char *build, const char *licenseStatus, const char *nsaClientData, uint32_t *transID) |
Send information about the system to Nalpeiron. Returns 0 on success and a negative number for an error. Username, applang, version, edition, build, and licenseStatus should be a ANSI C strings or a utf8 encoded unicode strings. See transaction ID discussion under NSATestConnection. NSASysInfo sends the following information:
|
||||||||||||||||||||||||||||||||||||||||
|
int NSASendCache(char *username, unsigned int32_t *transID) |
Check NSA's job cache. If not empty, send it. Returns 0 on success and a negative number for an error. Username should be a ANSI C string or a utf8 encoded unicode string. This function is provided for special circumstances but should be largely unnecessary as sending of the cache is automatic. Upon a successful completion of any of the functions about, the communication thread checks to see if the cache contains information. If it doesn, it is sent to Nalpeiron. See transaction ID discussion under NSATestConnection. | ||||||||||||||||||||||||||||||||||||||||
|
int NSAValidateLibrary(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 is returned. On mismatch, a negative error value is returned. Any negative return value, even if it is not a known error code, is cause to consider the library invalid. | ||||||||||||||||||||||||||||||||||||||||
|
int NSAGetVersion(char **version) |
Returns the version of the NSA library being accessed. | ||||||||||||||||||||||||||||||||||||||||
| int NSAGetStats( char **nsaStats) | Returns information about the NSA library's status. The following information is return in the form of a string.
<?xml version="1.0" encoding="UTF-8"?> <NSA Current Statistics> <OfflineMode>0</OfflineMode> <LocationInfo>1</LocationInfo> <Cache Thread> <Max Cache Que Len>25</Max Cache Que Len> <Current Cache Que Len>0</Current Cache Que Len> <Cache writes>1</Cache writes> <Cache fails>0</Cache fails> </Cache Thread> <Soap Pool> <Min Soap Threads>10</Min Soap Threads> <Max Soap Threads>10</Max Soap Threads> <Queued Jobs>0</Queued Jobs> <Running Jobs>0</Running Jobs> <Finished Jobs>145</Finished Jobs> </Soap Pool> </NSA Current Statistics>
|
||||||||||||||||||||||||||||||||||||||||
| int NSAGetComputerID(char **compID) | Get the unique identifier associated with an end user's computer. compID should be free with NSAFree. | ||||||||||||||||||||||||||||||||||||||||
| int NSAGetHostName(char **hostName) | Get the hostname used for all SOAP transactions. hostName should be freed with NSAFree. | ||||||||||||||||||||||||||||||||||||||||
| int NSAFree(void *) | 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 NSA library. This function is provided to ensure that memory allocated from the NSA heap is freed there. NSAFree should be used on the memory returned from NSAGetStats, ReturnVersion, GetComputerID, InternetHelloWorld, GetHostName, etc.. |