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 ruiSetProxy() handles setting and clearing the proxy related information.
The ruiSetProxy() 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.
ruiSetProxy() can be called between ruiCreateConfig() and ruiStopSDK(), and can be called zero or more times.
ruiSetProxy() 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 ruiSetProxy() function has the following parameters.
|
Parameter |
Description |
|
ruiInstance (RUIINSTANCE*) |
Pointer to the Usage Intelligence 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
The ruiSetProxy() function returns one of the return status constants below.
|
Return |
Description |
|
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 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. |