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 RUISDKOBJC object. This is done using initRegisterDefaultGraphicalReachOutHandler:registerHandler

(RUISDKOBJC) initRegisterDefaultGraphicalReachOutHandler: (BOOL)registerHandler

Constructor: Creates an instance of the SDK. Constructor must be paired with call to destructor when the client application is done using the RUI SDK. The constructor does not configure the RUI SDK (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:) nor start the RUI SDK (startSDK).

A typical client will create only a single instance of the RUI SDK. Creating more than one RUI SDK instance is allowed and is used to support clients that are plug-ins or other scenarios whereby multiple independent clients may co-exist in the same executable. Multiple RUI SDK instances perform independently of one another with the potential exception of shared or unshared configuration file (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:).

The constructor is a synchronous function, returning when all functionality is completed.

Parameters:

registerHandler (BOOL) - On platforms that contain a RUI SDK default graphical ReachOutTM handler,
automatically register that handler via setReachOutHandler:(). This is currently only Windows and MAC OS X.

Return Type:

The instantiated object, or null if there is a problem constructing the SDK instance.

Getting SDK Version Information

(NSString*) createSDKVersionString

Returns the version information for the RUI SDK instance in the supplied string parameter.

createSDKVersionString can be called more than once.

createSDKVersionString is a synchronous function, returning when all functionality is completed.

Return Type:

Formatted NSString containing the current RUI SDK version.

Getting Client ID

(NSString*) 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 NSString containing the current RUI client ID.

Initializing the configuration

The createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: method must be called in order to initialize the configuration. The method signature is as follows:

(RUIRESULTOBJC) (createConfig: (NSString*) configFilePath productID: (NSString*)productID appName: (NSString*)appName serverURL: (NSString*)serverURL protocol: (int32_t)protocol aesKeyHex: (NSString*)aesKeyHex multiSessionEnabled: (BOOL)multiSessionEnabled reachOutOnAutoSync: (BOOL)reachOutOnAutoSync

Parameters:

configFilePath (NSString*) - The directory to use for the RUI SDK instance’s configuration file. Cannot be empty; must
exist and be writeable.
serverURL (NSString*) - CallHome URL: Every product registered with Revulytics Usage Intelligence has its own unique CallHome URL
usually in the form ‘http://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 CallHome 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 CallHome URL.

productID (NSString*) - This is a unique 10-digit Product ID number that identifies your product with the Revulytics Usage Intelligence server.

appName (NSString*) - 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
protocol (int32) - Indicates whether HTTP + AES, HTTPS with fall back to HTTP + AES, or HTTPS is used to communicate with the RUI Server.
Valid values are RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION (1), RUI_PROTOCOL_HTTPS_WITH_FALLBACK (2), or RUI_PROTOCOL_HTTPS (3).
aesKeyHex (NSString*) - AES Key to use when protocol includes encryption; 32 hex chars (128 bit) key.
Used with protocol RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION and RUI_PROTOCOL_HTTPS_WITH_FALLBACK.

multiSessionEnabled (BOOL) - Whether multiple user sessions can be present in a single application runtime. Refer to Single vs. Multiple session modes.

reachOutOnAutoSync (BOOL) - 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 (initRegisterDefaultGraphicalReachOutHandler:) or a custom handler (setReachOutHandler:). This value may be changed at runtime using the call setReachOutOnAutoSync:reachOutOnAutoSyncSetting.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Function successful
* RUI_SDK_INTERNAL_ERROR_FATAL                  Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_CONFIG_ALREADY_CREATED                    Configuration has already been successfully created.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY      Some API parameter is expected to be non-empty, and is not.
* RUI_INVALID_PARAMETER_EXPECTED_NO_WHITESPACE  Some API parameter is expected to be free of whitespace, and is not.
* RUI_INVALID_PARAMETER_TOO_LONG                Some API parameter violates its allowable maximum length.
* RUI_INVALID_CONFIG_PATH                       The configFilePath is not a well-formed directory name.
* RUI_INVALID_CONFIG_PATH_NONEXISTENT_DIR       The configFilePath identifies a directory that does not exist.
* RUI_INVALID_CONFIG_PATH_NOT_WRITABLE          The configFilePath identifies a directory that is not writable.
* RUI_INVALID_PRODUCT_ID                        The productID is not a well-formed Revulytics Product ID.
* RUI_INVALID_SERVER_URL                        The serverURL is not a well-formed URL.
* RUI_INVALID_PROTOCOL                          The protocol is not a legal value.
* RUI_INVALID_AES_KEY_EXPECTED_EMPTY            The AES Key is expected to be NULL/empty, and it not.
* RUI_INVALID_AES_KEY_LENGTH                    The AES Key is not the expected length (32 hex chars; 16 bytes).
* RUI_INVALID_AES_KEY_FORMAT                    The AES Key is not valid hex encoding.

Code Example:

RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.

NSString* myURL = @"CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";
NSString* myProductID = @"INSERT-YOUR-PROD-ID";
NSString* myPath = @"<Path name to RUI writable directory>";
int32 myProtocol = RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION;
NSString* myKey = @"0123456789abcdeffedcba98765.5.10";
NSString* myAppName = "<YOUR APP NAME>";
BOOL      myReachOutAutoSyncSetting = YES;
BOOL      myMultiSessionSetting = NO;

[mySDK createConfig:myPath productID:productID appName:myAppName serverURL:myURL protocol:myProtocol aesKeyHex:myKey multiSessionEnabled:myMultiSessionSetting reachOutOnAutoSync:myReachOutAutoSyncSetting];

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 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 and stopSession should be used, and when tracking events, a session ID needs to be passed as a parameter.

Opt-Out mechanism

Starting from version 5.5.1, a new opt-out mechanism was introduced. Using this mechanism, if a user does not want to send tracking information to Revulytics, the function optOut: must be called after calling createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: 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 function 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 startSDK. 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 send in previous sessions) and disables all further functionality and communication with the server.

Returns:One of the return status constants below:
* 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 RUI Server has instructed a permanent disable.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STARTED  - SDK has already been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

Providing further 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

(RUIRESULTOBJC) setProductEdition: (NSString*)productEdition productLanguage: (NSString*)productLanguage productVersion: (NSString*)productVersion productBuildNumber: (NSString*)productBuildNumber

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:productLanguage:productVersion:productBuildNumber: can be called between createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: and stopSDK: and can be called zero or more times.

setProductEdition:productLanguage:productVersion:productBuildNumber: is a synchronous function returning when all functionality is completed.

Parameters:

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

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

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

productBuildNumber (NSString*) - The product build number that is to be set. Maximum length of 128 characters.

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

(RUIRESULTOBJC) setProductEdition: (NSString*)productEdition

This method allows you to set the edition of your product. An example of this would be when a single product can be licensed/run in different modes such as as “Home” and “Business”.

Parameters:

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

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

(RUIRESULTOBJC) setProductLanguage: (NSString*)productLanguage

This method allows you to set the language in that the client is viewing your product. This is useful for products that have been internationalized, so you can determine how many installations are running your software in a particular language. Please note this is different than the OS language that is collected automatically by the Revulytics Usage Intelligence SDK.

Parameters:

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

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

(RUIRESULTOBJC) setProductVersion: (NSString*)productVersion

This method is used to set the version number of the application being run. In most cases, this property would already have been set when initiating createConfig. So, this function normally only needs to be used if the version number changes during runtime such as after an update.

Parameters:

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

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

(RUIRESULTOBJC) setProductBuildNumber: (NSString*)productBuildNumber

This method is used to set the build number of the application being run. In most cases, this property would already have been set when initiating createConfig. So, this function normally only needs to be used if the build number changes during runtime such as after an update.

Parameters:

productBuildNumber (NSString*) - The product build number that is to be set. Maximum length of 128 characters.

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

License Management

(RUIRESULTOBJC) setLicenseDataKeyType: (int32_t)keyType keyExpired: (int32_t)keyExpired keyActivated: (int32_t)keyActivated keyBlacklisted: (int32_t)keyBlacklisted keyWhitelisted: (int32_t)keyWhitelisted sessionID: (NSString*)sessionID

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

setLicenseDataKeyType:keyExpired:keyActivated:keyBlacklisted:keyWhitelisted:sessionID: can be called between createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: and stopSDK: and can be called zero or more times. However, the usage requirements of the sessionID parameter are different if setLicenseDataKeyType:keyExpired:keyActivated:keyBlacklisted:keyWhitelisted:sessionID: is called before startSDK or called after startSDK:

* Before startSDK() regardless of multiSessionEnabled - sessionID must be empty.
* After  startSDK() and multiSessionEnabled = false   - sessionID must be empty.  This is similar to event tracking APIs.
* 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 be allowed.

setLicenseDataKeyType:keyExpired:keyActivated:keyBlacklisted:keyWhitelisted:sessionID: can be called while a New Registration is being performed (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:, 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.

setLicenseDataKeyType:keyExpired:keyActivated:keyBlacklisted:keyWhitelisted:sessionID:is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

keyType (int32_t) - One of the key types from the integer list below. Note that customer types can be used for application specific license types:

* RUI_KEY_TYPE_UNCHANGED  (-1) - Key Type is Unchanged (when in parameter) or Unknown (when out parameter)
* RUI_KEY_TYPE_EVALUATION (0)
* RUI_KEY_TYPE_PURCHASED  (1)
* RUI_KEY_TYPE_FREEWARE   (2)
* RUI_KEY_TYPE_UNKNOWN    (3)
* RUI_KEY_TYPE_NFR        (4) - Key Type is Not For Resale
* RUI_KEY_TYPE_CUSTOM1    (5)
* RUI_KEY_TYPE_CUSTOM2    (6)
* RUI_KEY_TYPE_CUSTOM3    (7)

expiredStatus (int32_t) - Indicates whether the client license has expired. One of the possible values:

* RUI_KEY_STATUS_UNCHANGED (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter).
* RUI_KEY_STATUS_NO        (0)  - Key Status is No.
* RUI_KEY_STATUS_YES       (1)  - Key Status is Yes.

activatedStatus (int32_t) - Indicates whether the client license has been activated. One of the possible values:

* RUI_KEY_STATUS_UNCHANGED (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter).
* RUI_KEY_STATUS_NO        (0)  - Key Status is No.
* RUI_KEY_STATUS_YES       (1)  - Key Status is Yes.

blacklistedStatus (int32_t) - Indicates whether the client license key has been blacklisted. One of the possible values:

* RUI_KEY_STATUS_UNCHANGED (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter).
* RUI_KEY_STATUS_NO        (0)  - Key Status is No.
* RUI_KEY_STATUS_YES       (1)  - Key Status is Yes.

whitelistedStatus (int32_t) - Indicates whether the client license key has been whitelisted. One of the possible values:

* RUI_KEY_STATUS_UNCHANGED (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter).
* RUI_KEY_STATUS_NO        (0)  - Key Status is No.
* RUI_KEY_STATUS_YES       (1)  - Key Status is Yes.

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY         The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE             The sessionID is not currently in use.

Changing ReachOut™ on 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:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: call. There may be certain cases when the application wants to either enable or disable this functionality during the application lifetime. The function setReachOutOnAutoSync:reachOutOnAutoSyncSetting allows the application to enable or disable this capability after createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: has been called.

(RUIRESULTOBJC) setReachOutOnAutoSync: (BOOL)reachOutOnAutoSyncSetting

Enables (true) or disables(false) the ReachOutTM on Autosync capability. Note if the call does not change the existing setting, the API will still return ok.

setReachOutOnAutoSync:reachOutOnAutoSyncSetting can be called between createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: and stopSDK: and can be called zero or more times.

Parameters:

reachOutOnAutoSyncSetting (BOOL) - Set to enable(YES) or disable(NO) ReachOut™ on Autosync setting.

Return Type:

Integer constant value with the following possible values:

* 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 DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.

Proxy Support

The RUI SDK V5 library supports communications through HTTP proxy servers 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 setProxyAddress handles setting and clearing the proxy related information.

(RUIRESULTOBJC) setProxyAddress: (NSString*)address port: (uint16_t)port username: (NSString*)username password: (NSString*)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 a 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 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 authenticating non-transparent proxy that will be used
                                                            unless communications fails, then falling back to using an
                                                            authenticating transparent proxy, then falling back to using no proxy.

setProxyAddress can be called between createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync: and stopSDK:, and can be called zero or more times.

setProxyAddress is a synchronous function, returning when all functionality is completed.

Parameters:

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.

Return Type:

Integer constant value with the following possible values:

* 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 RUISDKOBJC destructor are possible.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI 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.