Developer Zone

SDK Initialization and Configuration

The Revulytics Usage Intelligence V5 SDK is built to support running Revulytics Usage Intelligence in plug-in type environments. To accomplish this goal, applications must first create an instance of the Revulytics Usage Intelligence SDK by creating a new RUISDK object and using that object in subsequent calls. The call to ruiCreateInstance() must be paired with a call to ruiDestroyInstance() when the client application is done using the RUI SDK. ruiCreateInstance() does not configure the RUI SDK ( ruiCreateConfig() ) nor start the RUI SDK ( ruiStartSDK() ).

A typical client will create only a single instance of the RUI SDK. Creating more than one RUI SDK instance is allowed and is used to support clients that are plug-ins or other scenarios whereby multiple independent clients may co-exist in the same executable. Multiple RUI SDK instances perform independently of one another with the potential exception of shared or unshared configuration file ( ruiCreateConfig() ).

ruiCreateInstance() is a synchronous function, returning when all functionality is completed.

Before an application can start reporting usage to the Revulytics Usage Intelligence SDK, it must first provide some basic information such as the Product ID and the CallHome URL.

You should always fill in as much accurate and specific detail as possible since this data will be used by the Revulytics Usage Intelligence Analytics Server to generate the relevant reports. The more (optional) details you fill in about your product and its licensing state, the more filtering and reporting options will be available to you inside the Revulytics Usage Intelligence dashboard.

Creating the Revulytics Usage Intelligence SDK instance

RUIINSTANCE* ruiCreateInstance(bool registerDefaultGraphicalReachOutHandler)

The constructor creates the Revulytics Usage Intelligence SDK instance to be used by the application. All subsequent Revulytics Usage Intelligence SDK calls use the created instance as a parameter. This function also allocates the internal resources for the Revulytics Usage Intelligence SDK instance. Calls to ruiCreateConfig() and ruiStartSDK() follow the creation of this object.

Parameters:

registerDefaultGraphicalReachOutHandler (bool) - On platforms that contain a RUI SDK default graphical ReachOutTM handler (Windows and Mac OS X),
automatically register that handler via ruiSetReachOutHandler() .
Returns:The opaque handle to the RUI SDK instance, that is used in other API calls. NULL is returned if there is a creation error.

Destroying the Revulytics Usage Intelligence SDK instance

RUIRESULT ruiDestroyInstance(RUIINSTANCE* ruiInstance)

This function destroys an instance of the SDK, created with ruiCreateInstance().

The destructor is a synchronous function, returning when all functionality is completed.

Returns:One of the return status constants below.
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.

Getting SDK Version Information

RUIRESULT ruiGetSDKVersion(RUIINSTANCE* ruiInstance, char** sdkVersion)

ruiGetSDKVersion() will always allocate memory (regardless of return code), and the client application is responsible for freeing that memory via ruiFree() when the memory is no longer needed.

ruiGetSDKVersion() can be called between ruiCreateInstance() and ruiDestroyInstance(), and can be called more than once.

ruiGetSDKVersion() is a synchronous function, returning when all functionality is completed.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

sdkVersion (char**) - Receives the version string allocated by the RUI SDK; must be freed via ruiFree()

returns:

One of the return status constants below.

* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_INVALID_PARAMETER_EXPECTED_NON_NULL - Some API parameter is expected to be non-NULL, and is not.

Getting the Client ID

RUIRESULT ruiGetClientId(RUIINSTANCE* ruiInstance, char** clientID)

ruiGetClientId() will always allocate memory (regardless of return code) and the client application is responsible for freeing that memory via ruiFree() when the memory is no longer needed.

ruiGetClientId() can be called between ruiCreateInstance() and ruiDestroyInstance() and can be called more than once.

ruiGetClientId() is a synchronous function returning when all functionality is completed.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

clientId (char**) - Receives the client ID string allocation by the RUI SDK. Must be freed via ruiFree().
Returns the string “0”, if the client ID is not available.
returns:

One of the return status constants below.

* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error. No further API calls should be made.
* RUI_INVALID_PARAMETER_EXPECTED_NON_NULL - Some API parameter is expected to be non-NULL and is not.

Initializing the configuration

Before calling any other function other than the ruiCreateInstance() and ruiGetState(), the ruiCreateConfig() function must be called in order to initialize the configuration. The function signature is as follows:

RUIRESULT ruiCreateConfig(RUIINSTANCE* ruiInstance, const char* configFilePath, const char* productID, const char* appName, const char* serverURL, int32_t protocol, const char* aesKeyHex, bool multiSessionEnabled, bool reachOutOnAutoSync)

Creates a configuration for the RUI SDK instance. A configuration is passed on a file, specified by configFilePath, productID, and appName. If two or more RUI SDK instances, in the same process or in different processes, use the same values for these three parameters, then those RUI SDK instances are bound together through a shared configuration. When multiple different executables are being used, such usage is generally not desirable nor recommended. Instead, each executable should use a different appName value.

The RUI SDK has two communications modes: HTTPS or HTTP + AES-128 encryption. The mode is configured by protocol. When protocol is RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION or RUI_PROTOCOL_HTTPS_WITH_FALLBACK, the AES key must be supplied as a 128-bit (32 hex characters) hex-encoded string (aesKeyHex). When protocol is RUI_PROTOCOL_HTTPS, then aesKeyHex must be empty.

On first execution of a client application, no RUI SDK configuration file will exist. This situation is detected by the RUI SDK and will result in a New Registration message to the RUI Server at ruiStartSDK(). Once the configuration is received from the RUI Server, the RUI SDK writes the configuration file, that is then used for subsequent client application executions.

ruiCreateConfig() must be called before most other APIs and must only be successfully called once.

ruiCreateConfig() is a synchronous function, returning when all functionality is completed.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

configFilePath (const char*) - The directory to use for the RUI SDK instance’s configuration file. Cannot be empty; must
exist and be writable.

productID (const char*) - The Revulytics-supplied product ID for this client; 10 digits.

appName (const char*) - The customer-supplied application name for this client, to distinguish suites with the same
productID. Cannot be empty or contain white space; at most 16 UTF-8 character. More information about the purpose of the appName parameter can be found in the knowledge base article: https://support.revulytics.com/hc/en-us/articles/360024050091
serverURL (const char*) - The URL to use for New Registrations. Subsequent communications from the RUI SDK will either
use this URL or the URL supplied by the RUI Server). Cannot be empty. Cannot have a protocol prefix (e.g., no “http://” or “https://”).
protocol (int32_t) - Indicates whether HTTP + AES, HTTPS with fall-back to HTTP + AES, or HTTPS only is used to
communicate with the RUI Server. Valid values are: RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION, RUI_PROTOCOL_HTTPS_WITH_FALLBACK, or RUI_PROTOCOL_HTTPS.
aesKeyHex (const char*) - AES Key to use when protocol includes encryption (RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION or RUI_PROTOCOL_HTTPS_WITH_FALLBACK;
32 hex chars (16 bytes, 128 bit) key.
multiSessionEnabled (bool) - Indicates whether or not the client will explicitly manage sessionID’s via ruiStartSession()
and ruiStopSession(), and supply those sessionID’s to the various event tracking APIs.
reachOutOnAutoSync (bool) - Indicates whether or not a ReachOutTM should be requested as part of each RUI SDK Automatic Sync.
A ReachOutTM request will be made only if a ReachOutTM handler has been set by registering the default graphical handler (ruiCreateInstance) or a custom handler (ruiSetReachOutHandler()). This value may be changed at runtime using the call ruiSetReachOutOnAutoSync().
Returns:One of the return status constants below.
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_CONFIG_ALREADY_CREATED - Configuration has already been successfully created.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY - Some API parameter is expected to be non-empty, and is not.
* RUI_INVALID_PARAMETER_EXPECTED_NO_WHITESPACE - Some API parameter is expected to be free of white space, and is not.
* RUI_INVALID_PARAMETER_TOO_LONG - Some API parameter violates its allowable maximum length.
* RUI_INVALID_CONFIG_PATH - The configFilePath is not a well-formed directory name.
* RUI_INVALID_CONFIG_PATH_NONEXISTENT_DIR - The configFilePath identifies a directory that does not exist.
* RUI_INVALID_CONFIG_PATH_NOT_WRITABLE - The configFilePath identifies a directory that is not writable.
* RUI_INVALID_PRODUCT_ID - The productID is not a well-formed Revulytics Product ID.
* RUI_INVALID_SERVER_URL - The serverURL is not a well-formed URL.
* RUI_INVALID_PROTOCOL - The protocol is not a legal value.
* RUI_INVALID_AES_KEY_EXPECTED_EMPTY - The AES Key is expected to be NULL/empty, and it's not.
* RUI_INVALID_AES_KEY_LENGTH - The AES Key is not the expected length (32 hex chars).
* RUI_INVALID_AES_KEY_FORMAT - The AES Key is not valid hex encoding.

The following example shows how to initialize the Revulytics Usage Intelligence configuration:

// ruiCreateConfig example
bool useDefaultReachOutHandler = false;

RUIINSTANCE* mySDK = ruiCreateInstance(useDefaultReachOutHandler);

char* myPath = "PATH-TO-YOUR-CONFIG-FILE";
char* myURL = "CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";
char* myProductId = "INSERT-YOUR-PROD-ID";
char* myAppName = "MyApplication";
char* myKey = "0123456789abcdeffedcba9876543210";
bool multiSessionEnabled = false;
bool reachOutOnAutoSync = false;

RUIRESULT result = ruiCreateConfig(mySDK, myPath, myProductId, myAppName, myURL, RUN_PROTOCOL_HTTP_PLUS_ENCRYPTION, myKey, multiSessionEnabled, reachOutOnAutoSync);

Single vs. Multiple session modes

In desktop software, a single application instance would normally have only one single user session. This means that such an application would only show one window (or set of windows) to a single user and interaction is done with that single user. If the user would like to use two different sessions, two instances of the application would have to be loaded which would not affect each other. In such cases, you should use the single session mode that handles user sessions automatically and assumes that one process (instance) means one user session.

The multiple session mode must be used in multi-user applications, especially applications that have web interfaces. In such applications, many users may be using the same application process simultaneously. In such cases, the Revulytics Usage Intelligence SDK must be notified when user sessions start, stop and how to link events (see Feature / Event Tracking) to user sessions. When starting or stopping a user session, the functions ruiStartSession() and ruiStopSession() must be used. When tracking events on a per user basis a session ID needs to be passed as a parameter.

Opt-Out mechanism

Starting from version 5.1.0, a new opt-out mechanism was introduced. Using this mechanism, if a user does not want to send tracking infomation to Revulytics, the function ruiOptOut() must be called after calling ruiCreateConfig() and before ruiStartSDK(). When ruiOptOut() is called, the SDK sends a message to the server after startup (ruiStartSDK()). This message informs the server that this client has opted-out and the server will register the opt-out. This message is only sent to the server once. The opt-out flag on the server will be used for reporting opt-out statistics only. The SDK will send no further information to the server as long as the user is opted-out.

If ruiOptOut() is called before a new registration, the server will never have any data about that installation. If ruiOptOut() is called for an installation that was already being tracked, the server will still contain the data that had been collected in the past and no past data is deleted.

The application must keep calling ruiOptOut() before every startup as long as the user wants to stay opted-out. If this function is not called, then the SDK assumes that the user is opting-in again and will start tracking normally.

Note that when an installation is not opted-out, it communicates with the server immediately on calling ruiStartSDK(). At this point, the SDK attempts to sync data regarding past application and event usage that had not been synced yet, and also system and product information such as OS version, CPU, GPU, product version, product edition, etc.

RUIRESULT ruiOptOut(RUIINSTANCE* ruiInstance)

Instructs the SDK to send a message to the server to indicate that this user is opting-out (if not already sent in previous sessions) and disables all further functionality and communication with the server.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()
Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STARTED  - SDK has already been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

Providing further data

RUI SDK V5 requires that the application provide product data every time the RUI SDK instance is run. In addition you can optionally set License data for the application. Finally, if you are using proxies to access the internet, there is a function to set up the required information for connecting through that proxy.

Product Details

RUIRESULT ruiSetProductData(RUIINSTANCE* ruiInstance, const char* productEdition, const char* productLanguage, const char* productVersion, const char* productBuildNumber)

This function sets or clears the product data. NOTE: The product data must be set every time the RUI SDK instance is run.

NOTE: This is different than V4 of the RUI (Trackerbird) SDK where the supplied product data was stored in the SDK configuration file and if it was not supplied, the values in the configuration file were used.

ruiSetProductData() can be called between ruiCreateConfig() and ruiStopSDK() and can be called zero or more times.

ruiSetProductData() is a synchronous function returning when all functionality is completed.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

productEdition (const char*) - The product edition that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

productLanguage (const char*) - The product language that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

productVersion (const char*) - The product version that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

productBuildNumber (const char*) - The product build number that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

RUIRESULT ruiSetProductEdition(RUIINSTANCE* ruiInstance, const char* productEdition)

This function allows you to set the edition of your product. An example of this would be when a single product can be licensed/run in different modes such as as “Home” and “Business”.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

productEdition (const char*) - The product edition that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

RUIRESULT ruiSetProductLanguage(RUIINSTANCE* ruiInstance, const char* productLanguage)

This function allows you to set the language that the client is viewing your product. This is useful for products that have been internationalized, so you can determine how many installations are running your software in a particular language. Please note this is different than the OS language that is collected automatically by the Revulytics Usage Intelligence SDK.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

productLanguage (const char*) - The product language that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

RUIRESULT ruiSetProductVersion(RUIINSTANCE* ruiInstance, const char* productVersion)

This function is used to set the version of the application being run.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

productVersion (const char*) - The product version that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

RUIRESULT ruiSetProductBuildNumber(RUIINSTANCE* ruiInstance, const char* productBuildNumber)

This function is used to set the build number of the application being run.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

productBuildNumber (const char*) - The product build number that is to be set. Maximum length of 128 characters. NOTE: A NULL value removes any previous value

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

License Management

RUIRESULT ruiSetLicenseData(RUIINSTANCE* ruiInstance, int32_t keyType, int32_t keyExpired, int32_t keyActivated, int32_t keyBlacklisted, int32_t keyWhitelisted, const char* sessionID)

Sets or clears the license data. The legal parameter values include RUI_KEY_STATUS_UNCHANGED (-1). NOTE: Different from the V4 of the RUI SDK, a sessionID parameter can be supplied.

ruiSetLicenseData() can be called between ruiCreateConfig() and ruiStopSDK() and can be called zero or more times. However, the usage requirements of the sessionID parameter are different if ruiSetLicenseData() is called before ruiStartSDK() or called after ruiStartSDK()

* Before startSDK regardless of multiSessionEnabled - sessionID must be empty.
* After  startSDK and multiSessionEnabled = false   - sessionID must be empty.  This is similar to event tracking APIs.
* After  startSDK and multiSessionEnabled = true    - sessionID must be a current valid value used in startSession(), or
                                                      it can be empty.  This is different than normal event tracking APIs,
                                                      whereby a empty value is not allowed.

ruiSetLicenseData() can be called while a New Registration is being performed (ruiCreateConfig(), ruiStartSDK()). However, the event data is not written to the log file until the New Registration completes, and if the New Registration fails, the data will be lost.

ruiSetLicenseData() is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

The keyType parameter can be set to any of the constant types below. Please note that the 3 custom values may be used freely to denote your own custom license types.

* RUI_KEY_TYPE_UNCHANGED  (-1)
* RUI_KEY_TYPE_EVALUATION (0)
* RUI_KEY_TYPE_PURCHASED  (1)
* RUI_KEY_TYPE_FREEWARE   (2)
* RUI_KEY_TYPE_UNKNOWN    (3)
* RUI_KEY_TYPE_NFR        (4)
* RUI_KEY_TYPE_CUSTOM1    (5)
* RUI_KEY_TYPE_CUSTOM2    (6)
* RUI_KEY_TYPE_CUSTOM3    (7)

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

keyType (int32_t) - One of the key types from the list shown above.

keyExpired (int32_t) - Indicates whether the client license has expired. One of the values below:

* RUI_KEY_STATUS_UNCHANGED (-1)
* RUI_KEY_STATUS_NO        (0)
* RUI_KEY_STATUS_YES       (1)

keyActivated (int32_t) - Indicates whether the client license has been activated. One of the values below:

* RUI_KEY_STATUS_UNCHANGED (-1)
* RUI_KEY_STATUS_NO        (0)
* RUI_KEY_STATUS_YES       (1)

keyBlacklisted (int32_t) - Indicates whether the client license key has been blacklisted. One of the values below:

* RUI_KEY_STATUS_UNCHANGED (-1)
* RUI_KEY_STATUS_NO        (0)
* RUI_KEY_STATUS_YES       (1)

keyWhitelisted (int32_t) - Indicates whether the client license key has been whitelisted. One of the values below:

* RUI_KEY_STATUS_UNCHANGED (-1)
* RUI_KEY_STATUS_NO        (0)
* RUI_KEY_STATUS_YES       (1)

sessionId (const char*) - Optional SessionId parameter to associate keys to a specific session. NULL if not used.

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY - The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY - The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT - The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG - The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE - The sessionID is not currently in use.

Changing ReachOutTMon Autosync Setting

The flag to determine whether or not a ReachOutTM should be requested as part of each RUI SDK Automatic Sync is initially set in the ruiCreateConfig() call. There may be certain cases when the application wants to either enable or disable this functionality during the application lifetime. The function ruiSetReachOutOnAutoSync() allows the application to enable or disable this capability after ruiCreateConfig() has been called.

RUIRESULT ruiSetReachOutOnAutoSync(RUIINSTANCE* ruiInstance, bool reachOutOnAutoSyncSetting)

Enables (true) or disables(false) the ReachOutTMon Autosync capability. Note if the call does not change the existing setting, the API will still return RUI_OK.

ruiSetReachOutOnAutoSync() can be called between ruiCreateConfig() and ruiStopSDK() and can be called zero or more times.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

reachOutOnAutoSyncSetting (bool*) - Enable (true) or disable(false) the ReachOut on Autosync capability.

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

Proxy Support

The RUI SDK V5 library supports communications through HTTP proxy servers on all major operating system types: Windows, Linux, and Mac OS X. Application developers are responsible for obtaining proxy credentials (if the proxy requires it) and setting those credentials in the RUI SDK so communications can use the credentials for the proxy. The function ruiSetProxy() handles setting and clearing the proxy related information.

RUIRESULT ruiSetProxy(RUIINSTANCE* ruiInstance, const char* address, uint16_t port, const char* username, const char* password)

Sets or clears the data to be used with a proxy. If there is no proxy between the RUI SDK and the RUI Server, there is no need to use this function. The address can be either empty (for transparent proxy servers) or non-empty. The username and password must both be empty (non-authenticating proxy) or both be non-empty (authenticating proxy). The port is only used for non-transparent proxy servers, hence port must be zero if address is empty, otherwise port must be non-zero. The RUI SDK uses the proxy data in multiple ways to attempt to communicate via a proxy. The allowed parameter combinations and their usage are as follows:

address,       port,     username,       password

empty,          0,         empty,          empty          - Resets the proxy data to its initial state, no proxy server is
                                                            used, and the RUI Server is contacted directly.

non-empty,      not 0,     empty,          empty          - Identifies a non-authenticating non-transparent proxy that will be used
                                                            unless communications fails, then falling back to using no proxy.

empty,          0,         non-empty,      non-empty      - Identifies an authenticating transparent proxy that will be used
                                                            unless communications fails, then falling back to using no proxy.

non-empty,      not 0,     non-empty,      non-empty      - Identifies an non-transparent authenticating proxy that will be used
                                                            unless communications fails, then falling back to using an
                                                            authenticating transparent proxy, then falling back to using no proxy.

ruiSetProxy() can be called between createConfig() and ruiStopSDK(), and can be called zero or more times.

ruiSetProxy() is a synchronous function, returning when all functionality is completed.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

address (const char*) - The server name or IP address (dot notation) for the proxy server.

port (uint16_t) - The port for the proxy server; only used with non-transparent proxy, port != 0 if and only if address non-empty.

username (const char*) - The proxy username; username and password must both be empty or both be non-empty.

password (const char*) - The proxy password; username and password must both be empty or both be non-empty.

Returns:One of the return status constants below:
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_INVALID_PROXY_CREDENTIALS - The proxy username and password are not an allowable combination.
* RUI_INVALID_PROXY_PORT - The proxy port was not valid.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.