Developer Zone

SDK Configuration

Before an application can start reporting usage to the Revulytics Usage Intelligence SDK, it must first provide some basic information such as the location of where the SDK will create and save its working files, the application Product ID and the CallHome URL.

You should always attempt to fill in as much accurate and specific details as possible since this data will then 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.

SDK Object Initialization

Before beginning any operation, you must first create an instance of the RUISDK object. The constructor is defined below.

SDKImpl(boolean registerDefaultGraphicalReachOutHandler)

Constructor: Creates an instance of the SDK. The constructor does not configure the RUI SDK (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean)) nor start the RUI SDK (startSDK()).

Parameters:

registerDefaultGraphicalReachOutHandler (boolean) - For Java SDK value must be false. There is no default Graphical ReachOut Handler for the Java SDK.

Getting SDK Version Information

String getSDKVersion()

Returns the version information for the RUI SDK instance.

getSDKVersion() can be called more than once.

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

Return Type:

Formatted String containing the RUISDK version information.

Getting the Client ID

String getClientID()

Returns the client ID for the RUI SDK instance.

getClientID() can be called more than once.

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

Return Type:

Formatted String containing the RUISDK version information. Returns String of “0” if the client ID is not available.

Initializing the configuration

The createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) method must be called in order to initialize the configuration. The method signature is as follows:

RUIResult createConfig(String configFilePath, String productID, String appName, String serverURL, RUIProtocol protocol, String aesKeyHex, boolean multiSessionEnabled, boolean 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 the parameter protocol. When protocol is set to HTTP_PLUS_ENCRYPTION or HTTPS_WITH_FALLBACK, the AES key must be supplied as a 128-bit hex-encoded string (aesKeyHex). When protocol is 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 startSDK(). 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.

createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) must be called before most other APIs and must only be successfully called once.

createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) is a synchronous function, returning when all functionality is completed.

Parameters:

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

productID (String) - The Revulytics-supplied product ID for this client; 10 digits. You obtain this ID after registering with Revulytics.

appName (String) - 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 characters.
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 (String) - Every product registered with Revulytics Usage Intelligence has its own unique URL usually in the form ‘xxxxx.tbnet1.com’. This URL is generated automatically on
account creation and is used by the SDK to communicate with the Revulytics Usage Intelligence server. You can get this URL from the Developer Zone once you login to the Usage Intelligence dashboard. If you have a Premium product account you may opt to use your own custom server URL (such as http://updates.yourdomain.com) that must be setup as a CNAME DNS entry pointing to your unique Revulytics Usage Intelligence URL. Please note that before you can use your own custom URL you must first inform Revulytics Usage Intelligence support (support-rui@revulytics.com) to register your domain with the Revulytics Usage Intelligence server. If you fail to do this, the server will automatically reject any incoming calls using yourdomain.com as a server URL. The URL should not contain a protocol prefix.
protocol (RUIProtocol) - Indicates whether HTTP + AES, HTTPS with fall-back to HTTP + AES, or HTTPS is used to communicate with the RUI Server.
Valid choices can be found in the RUIProtocol enum and are: HTTP_PLUS_ENCRYPTION (1), HTTPS_WITH_FALLBACK (2), or HTTPS (3).

aesKeyHex (String) - AES Key to use when protocol includes encryption (HTTP_PLUS_ENCRYPTION or HTTPS_WITH_FALLBACK); 32 hex chars (128 bit) key.

multiSessionEnabled (boolean) - Indicates whether or not the client will explicitly manage sessionID’s via startSession(String) and stopSession(String),
and supply those sessionID’s to the various event tracking APIs. Refer to Single vs. Multiple session modes.
reachOutOnAutosync (boolean) - 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 (SDKImpl(boolean)) or a custom handler (setReachOutHandler(RUIReachOutHandler)). This value may be changed at runtime using the call setReachOutOnAutoSync(boolean).

Return Type:

RUIResult enum value with the following possible values:

* OK                                        Function successful.
* SDK_INTERNAL_ERROR_FATAL                  Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* CONFIG_ALREADY_CREATED                    Configuration has already been successfully created.
* INVALID_PARAMETER_EXPECTED_NON_EMPTY      Some API parameter is expected to be non-empty, and is not.
* INVALID_PARAMETER_EXPECTED_NO_WHITESPACE  Some API parameter is expected to be free of white space, and is not.
* INVALID_PARAMETER_TOO_LONG                Some API parameter violates its allowable maximum length.
* INVALID_CONFIG_PATH                       The configFilePath is not a well-formed directory name.
* INVALID_CONFIG_PATH_NONEXISTENT_DIR       The configFilePath identifies a directory that does not exist.
* INVALID_CONFIG_PATH_NOT_WRITABLE          The configFilePath identifies a directory that is not writable.
* INVALID_PRODUCT_ID                        The productID is not a well-formed Revulytics Product ID.
* INVALID_SERVER_URL                        The serverURL is not a well-formed URL.
* INVALID_PROTOCOL                          The protocol is not a legal value.
* INVALID_AES_KEY_EXPECTED_EMPTY            The AES Key is expected to be NULL/empty, and it's not.
* INVALID_AES_KEY_LENGTH                    The AES Key is not the expected length of 32 hex chars.
* INVALID_AES_KEY_FORMAT                    The AES Key is not valid hex encoding.

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 that 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 needs to be used in multi-user applications, especially applications that have web interfaces. In such applications, a number of users might be using the same application process simultaneously. In such cases, you need to manually tell the Revulytics Usage Intelligence SDK when user sessions start and stop, and also how to link events (see Feature / Event Tracking) to user sessions. To do this, when starting or stopping a user session, the methods startSession(String) and stopSession(String) should be used, and when tracking events, 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 information to Revulytics, the method optOut must be called after calling createConfig and before startSDK. When optOut is called, the SDK sends a message to the server after startup (startSDK). 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.

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

The SDK will send no further information to the server as long as the user is opted-out. The application must keep calling optOut before every startup as long as the user wants to stay opted-out. If this method 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 optOut. 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 optOut()

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.

Returns:One of the return status constants below:
* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is permitted.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STARTED          SDK has already been successfully started.
* SDK_ALREADY_STOPPED          SDK has already been successfully stopped.

Providing Product 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 setProductData(String productEdition, String productLanguage, String productVersion, String productBuildNum)

Sets or clears the product data. NOTE: The product data must be set every time the RUI SDK instance is run. 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.

setProductData(String, String, String, String) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times.

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

Parameters:

productEdition (String) - The product edition that is to be set. Maximum length of 128 characters.

productLanguage (String) - The product language that is to be set. Maximum length of 128 characters.

productVersion (String) - The product version that is to be set. Maximum length of 128 characters.

productBuildNum (String) - The product build number that is to be set. Maximum length of 128 characters.

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STARTED          SDK has already been successfully stopped.

RUIResult setProductEdition(String productEdition)

Sets or clears the product data. NOTE: The product data must be set every time the RUI SDK instance is run. 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.

setProductEdition(String) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times.

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

Parameters:

productEdition (String) - The product edition that is to be set. Maximum length of 128 characters.

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STARTED          SDK has already been successfully stopped.

RUIResult setProductLanguage(String productLanguage)

Sets or clears the product data. NOTE: The product data must be set every time the RUI SDK instance is run. 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.

setProductLanguage(String) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times.

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

Parameters:

productLanguage (String) - The product language that is to be set. Maximum length of 128 characters.

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STARTED          SDK has already been successfully stopped.

RUIResult setProductVersion(String productVersion)

Sets or clears the product data. NOTE: The product data must be set every time the RUI SDK instance is run. 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.

setProductVersion(String) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times.

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

Parameters:

productVersion (String) - The product version number that is to be set. Maximum length of 128 characters.

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STARTED          SDK has already been successfully stopped.

RUIResult setProductBuildNumber(String productBuildNum)

Sets or clears the product data. NOTE: The product data must be set every time the RUI SDK instance is run. 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.

setProductBuildNumber(String) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times.

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

Parameters:

productBuildNum (String) - The product build number that is to be set. Maximum length of 128 characters.

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STOPPED          SDK has already been successfully stopped.

License Management

RUIResult setLicenseData(RUIKeyType keyType, RUIKeyStatus keyExpired, RUIKeyStatus keyActivated, RUIKeyStatus keyBlacklisted, RUIKeyStatus keyWhitelisted)
RUIResult setLicenseData(RUIKeyType keyType, RUIKeyStatus keyExpired, RUIKeyStatus keyActivated, RUIKeyStatus keyBlacklisted, RUIKeyStatus keyWhitelisted, String sessionID)

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

setLicenseData(RUIKeyType, RUIKeyStatus, RUIKeyStatus, RUIKeyStatus, RUIKeyStatus) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times. However, the usage requirements of the sessionID parameter are different if setLicenseData(RUIKeyType, RUIKeyStatus, RUIKeyStatus, RUIKeyStatus, RUIKeyStatus) is called before startSDK() or called after startSDK():

* Before startSDK regardless of multiSessionEnabled - use method without sessionID
* After  startSDK and multiSessionEnabled = false   - use method without sessionID
* 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.

setLicenseData(RUIKeyType, RUIKeyStatus, RUIKeyStatus, RUIKeyStatus, RUIKeyStatus) can be called while a New Registration is being performed (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean), startSDK()). 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.

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

Parameters:

keyType (RUIKeyType) - One of the key types from the RUIKeyType enum. Note that custom types can be used for application specific license types:

* UNCHANGED (-1)
* EVALUATION (0)
* PURCHASED (1)
* FREEWARE (2)
* UNKNOWN (3)
* NFR (4) // Not For Resale
* CUSTOM1 (5)
* CUSTOM2 (6)
* CUSTOM3 (7)

keyExpired (RUIKeyStatus) - Indicates whether the client license has expired. Use one of the RUIKeyStatus enum choices for the values:

* UNCHANGED (-1)
* NO (0)
* YES (1)

keyActivated (RUIKeyStatus) - Indicates whether the client license has been activated. Use one of the RUIKeyStatus enum choices for the values:

* UNCHANGED (-1)
* NO (0)
* YES (1)

keyBlacklisted (RUIKeyStatus) - Indicates whether the client license key has been blacklisted. Use one of the RUIKeyStatus enum choices for the values:

* UNCHANGED (-1)
* NO (0)
* YES (1)

keyWhitelisted (RUIKeyStatus) - Indicates whether the client license key has been whitelisted. Use one of the RUIKeyStatus enum choices for the values:

* UNCHANGED (-1)
* NO (0)
* YES (1)

sessionID (String) - An optional session ID complying with above usage (content conditioning and validation rules in startSession(String)).

Return Type:

RUIResult enum value with the following possible values:

* OK                                         Function successful.
* SDK_INTERNAL_ERROR_FATAL                   Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                                A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED                   The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                              The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                              Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                         Configuration has not been successfully created.
* SDK_ALREADY_STOPPED                        SDK has already been successfully stopped.
* INVALID_SESSION_ID_EXPECTED_EMPTY          The sessionID is expected to be empty, and it was not.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY      The sessionID is expected to be non-empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT               The sessionID violates its allowable minimum length. Minimum length is 10.
* INVALID_SESSION_ID_TOO_LONG                The sessionID violates its allowable maximum length. Maximum length is 64.
* 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 createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) call. There may be certain cases when the application wants to either enable or disable this functionality during the application lifetime. The function ruiSetReachOutOnAutoSync(boolean) allows the application to enable or disable this capability after createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) has been called.

RUIResult setReachOutOnAutoSync(boolean 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 OK.

ruiSetReachOutOnAutoSync(boolean) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int) and can be called zero or more times.

Parameters:

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

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* INVALID_SDK_OBJECT           SDK Instance parameter is NULL or invalid.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_ALREADY_STOPPED          SDK has already been successfully stopped.

Proxy Support

The RUI SDK V5 library supports communications through proxies 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 setProxy(String, short, String, String) handles setting and clearing the proxy related information.

RUIResult setProxy(String address, short port, String username, String 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 named proxy that will be used
                                                            unless communications fails, then falling back to using no proxy.

empty,          0,         non-empty,      non-empty      - Identifies an authenticating unnamed 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 authenticating named proxy that will be used
                                                            unless communications fails, then falling back to using an
                                                            authenticating unnamed proxy, then falling back to using no proxy.

setProxy(String, short, String, String) can be called between createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and stopSDK(int), and can be called zero or more times.

setProxy(String, short, String, String) is a synchronous function, returning when all functionality is completed.

Parameters:

address (String) - The server name or IP address (dot notation) for the named proxy.

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

username (String) - The named proxy username; username and password must both be empty or both be non-empty.

password (String) - The named proxy password; username and password must both be empty or both be non-empty.

Return Type:

RUIResult enum value with the following possible values:

* OK                           Function successful.
* SDK_INTERNAL_ERROR_FATAL     Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                  A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED     The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED           Configuration has not been successfully created.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* SDK_ALREADY_STOPPED          SDK has already been successfully stopped.
* INVALID_PROXY_CREDENTIALS    The proxy username and password are not an allowable combination.
* INVALID_PROXY_PORT           The proxy port was not valid.