Files
file	nsaH.h
	Analytics (NSA) Nalpeiron V10 library functions.

Functions
int	NSAValidateLibrary (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	NSAGetVersion (char **version)
	Gets the version of the NSA library being accessed. More...

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

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

int	NSACheckCache (uint64_t *cacheSize)
	Checks to see if any analytics information is stored in the cache files. More...

int	NSATestConnection2 (const char nsaClientData, uint32_t transID)
	Tests the network connection to Nalpeiron. NSATestConnection2 bypasses the normal thread pool and connects directly and immediately to Nalpeiron. The function does obey the offline mode setting and the privacy setting. If either are set to disallow connections, NSATestConnection2 will return and appropriate error. More...

int	NSATestConnection (const char nsaClientData, uint32_t transID)
	Tests the network connection to Nalpeiron. More...

int	NSAAppStart (const char username, const char nsaClientData, uint32_t *transID)
	Records startup of your application. More...

int	NSAAppStop (const char username, const char nsaClientData, uint32_t *transID)
	Records the shutdown of your application. More...

int	NSALogin (const char username, const char nsaClientData, uint32_t *transID)
	Records login of username. More...

int	NSALogout (const char username, const char nsaClientData, uint32_t *transID)
	Records logout of username. More...

int	NSAFeatureStart (const char username, const char featureCode, const char nsaClientData, uint32_t transID)
	Records the start of a feature specified by featureCode and used by username. More...

int	NSAFeatureStop (const char username, const char featureCode, const char nsaClientData, uint32_t transID)
	Records the end of use of a feature specified by featureCode and used by username. More...

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

int	NSASysInfo (const char username, const char applang, const char version, const char edition, const char build, const char licenseStat, const char nsaClientData, uint32_t transID)
	Sends information about the end user's system to Nalpeiron. In addition to the parameters the function will send the following information. More...

int	NSASendCache (const char username, uint32_t transID)
	If a cache file of analytics data exists on the end user's system send it to Nalpeiron. Cache files are created when a system is offline or has been placed in offline mode. More...

int	NSAGetPrivacy ()
	Checks the current privacy setting. If privacy is unset, the privacy setting used by the library will be the one stamped into it. More...

int	NSASetPrivacy (uint16_t nsaPriv)
	Sets the library's privacy setting to nsaPriv. More...

int	NSAGetStats (char **nsaStats)
	Returns status information from the NSA library. More...

int	NSAFree (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 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 the NSA library. More...

Detailed Description

Function Documentation

int NSAAppStart	(	const char *	username,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Records startup of your application.

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSAAppStop	(	const char *	username,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Records the shutdown of your application.

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSACheckCache ( uint64_t * cacheSize )

Checks to see if any analytics information is stored in the cache files.

Parameters

cacheSize is the size of the cache file in bytes. 0 indicates an empty cache. NOTE an empty cache is 5 bytes. This routine will return a size of 0 bytes in that case.

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

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.

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
exceptionCode	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
description	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSAFeatureStart	(	const char *	username,
		const char *	featureCode,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Records the start of a feature specified by featureCode and used by username.

Parameters

featureCode	a NULL terminated, UTF-8 encoded string containing the five (5) character feature code of the feature to be checked out.
username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSAFeatureStop	(	const char *	username,
		const char *	featureCode,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Records the end of use of a feature specified by featureCode and used by username.

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
featureCode	a NULL terminated, UTF-8 encoded string containing the five (5) character feature code of the feature to be checked out.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSAFree ( 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 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 the NSA 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 NSAGetComputerID ( 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 NSAFree.

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

int NSAGetHostName ( 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 NSAFree.

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

int NSAGetPrivacy ( )

Checks the current privacy setting. If privacy is unset, the privacy setting used by the library will be the one stamped into it.

Returns: = 0 No privacy; = 1 Privacy enabled.; < 0 A negative error value is returned (Nalpeiron V10 error returns)

int NSAGetStats ( char ** nsaStats )

Returns status information from the NSA library.

Parameters

nsaStats

statistics from the NSA library as a NULL terminated, UTF-8, XML string. The format of the return is:

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

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

int NSAGetVersion ( char ** version )

Gets the version of the NSA library being accessed.

Parameters

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

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

int NSALogin	(	const char *	username,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Records login of username.

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSALogout	(	const char *	username,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Records logout of username.

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSASendCache	(	const char *	username,
		uint32_t *	transID
	)

If a cache file of analytics data exists on the end user's system send it to Nalpeiron. Cache files are created when a system is offline or has been placed in offline mode.

Parameters

username a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.

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

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

int NSASetPrivacy ( uint16_t nsaPriv )

Sets the library's privacy setting to nsaPriv.

Parameters

nsaPriv privacy value for the library. Possible values for setting are 0 "no privacy" or 1 "privacy enabled".

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

int NSASysInfo	(	const char *	username,
		const char *	applang,
		const char *	version,
		const char *	edition,
		const char *	build,
		const char *	licenseStat,
		const char *	nsaClientData,
		uint32_t *	transID
	)

Sends information about the end user's system to Nalpeiron. In addition to the parameters the function will send the following information.

  applanguage     passed in app language
  bitage          32 or 64
  city            city
  computerid      the end user's computer ID
  cores           number of processors or cores
  country         country name
  customerid      your customer ID
  date            date and time
  host name       computer name
  location        countryid- Two character country code
  memory          amount of memory in Meg.
  NSA version     version number of the NSA Library
  operatingsystem OS (Linux, Windows, OSX, etc)
  oslanguage      default OS language
  proc            processor information
  productid       your product ID
  productstatus   passed in License Status
  profile         type of system(laptop or desktop)
  region          state, territory, region as appropriate
  screenresx      screen width
  screenresy      screen height
  username        username as passed into NSASysInfo
  zipcode         zipcode as appropriate

Parameters

username	a NULL terminated, UTF-8 encoded username that will be passed to the Nalpeiron server or daemon with your call.
applang	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
version	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
edition	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
build	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
licenseStat	a NULL terminated, UTF-8 encoded string that will be passed to the Nalpeiron server or daemon with your call.
nsaClientData	(reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.
transID	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.

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

int NSATestConnection	(	const char *	nsaClientData,
		uint32_t *	transID
	)

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 NSATestConnection2 (NSATestConnection2) instead

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

int NSATestConnection2	(	const char *	nsaClientData,
		uint32_t *	transID
	)

Tests the network connection to Nalpeiron. NSATestConnection2 bypasses the normal thread pool and connects directly and immediately to Nalpeiron. The function does obey the offline mode setting and the privacy setting. If either are set to disallow connections, NSATestConnection2 will return and appropriate error.

Parameters

nsaClientData (reserved for future use) a NULL terminated, UTF-8 encoded XML fragment containing whatever data you would like to pass to the Nalpeiron server or daemon with your call.

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

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

int NSAValidateLibrary	(	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 conjunction 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 conjunction with the library would be 5678.

Returns: = 0(zero) is returned if the customerID/productID passed into the function match those from the library. On mismatch, a negative error value is returned.; < 0 On mismatch, a negative error value is returned (Nalpeiron V10 error returns)

Files

Functions

Detailed Description

Function Documentation