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 setProxyAddress: handles setting and clearing the proxy related information.
The setProxyAddress: 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.
setProxyAddress: can be called between createConfig and stopSDK:, and can be called zero or more times.
setProxyAddress: is a synchronous function, returning when all functionality is completed.
RUIRESULT ruiSetProxy(RUIINSTANCE* ruiInstance, const char* address, uint16_t port, const char* username, const char* 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 setProxyAddress: function has the following parameters.
|
Parameter |
Description |
|
address (NSString*) |
The server name or IP address (dot notation) for the non-transparent proxy. |
|
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 (NSString*) |
The proxy username; username and password must both be empty or both be non-empty. |
|
password (NSString*) |
The proxy password; username and password must both be empty or both be non-empty. |
Returns
The setProxyAddress: function returns one of the return status constants below.
|
Return |
Description |
|
RUI_OK |
Function successful. |
|
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. stopSDK: and Objective-C instance release are possible. |
|
RUI_SDK_PERMANENTLY_DISABLED |
The 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. |