Proxy Support

The Usage Intelligence SDK V5 library supports communications through proxies on all major operating system types: Windows, Linux, and macOS. Application developers are responsible for obtaining proxy credentials (if the proxy requires it) and setting those credentials in the SDK so communications can use the credentials for the proxy. The function setProxy() handles setting and clearing the proxy related information.

The setProxy() function sets or clears the data to be used with a proxy. If there is no proxy between the SDK and the 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.

setProxy() can be called between createConfig() and stopSDK(), and can be called zero or more times.

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

setProxy()

RUIResult setProxy(String address, short port, String username, String password)

Permitted Parameter Combinations

The 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:

setProxy() Permitted Parameter Combinations

address	port	username	password	Description
empty	0	empty	empty	Resets the proxy data to its initial state, no proxy server is used, and the 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.

Parameters

The setProxy() function has the following parameters.

setProxy() Parameters

Parameter	Description
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.

Returns

The setProxy() function returns RUIResult enum value with the following possible values:

setProxy() Returns

Return	Description
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 Server has instructed a permanent disable.
SDK_SUSPENDED	The 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_PROXY_CREDENTIALS	The proxy username and password are not an allowable combination.
INVALID_PROXY_PORT	The proxy port was not valid.