Proxy Support
The Usage Intelligence SDK V5 library supports communications through HTTP proxy servers 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 RUISDK.SetProxy handles setting and clearing the proxy related information.
The RUISDK.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.
RUISDK.SetProxy can be called between RUISDK.CreateConfig and RUISDK.StopSDK, and can be called zero or more times.
RUISDK.SetProxy is a synchronous function, returning when all functionality is completed.
RUIResult RUISDK.SetProxy (String address, UInt16 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:
|
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 RUISDK.SetProxy function has the following parameters.
|
Parameter |
Description |
|
address (String) |
The server name or IP address (dot notation) for the proxy server. |
|
port (UInt16) |
The port for the proxy server; only used with non-transparent proxy, port != 0 if and only if address non-empty. |
|
username (String) |
The proxy username; username and password must both be empty or both be non-empty. |
|
password (String) |
The proxy password; username and password must both be empty or both be non-empty. |
Returns
The RUISDK.SetProxy function returns a RUIResult enum value with the following possible values:
|
Return |
Description |
|
ok |
Function successful. |
|
sdkInternalErrorFatal |
Irrecoverable internal fatal error. No further API calls should be made. |
|
sdkAborted |
A required New Registration has failed, and hence the SDK is aborted. RUISDK.StopSDK and RUISDK destructor are possible. |
|
sdkSuspended |
The Server has instructed a temporary back-off. |
|
sdkPermantelyDisabled |
The Server has instructed a permanent disable. |
|
sdkOptedOut |
|
|
configNotCreated |
Configuration has not been successfully created. |
|
sdkAlreadyStopped |
SDK has already been successfully stopped. |