Initializing the Configuration

Before calling any other function other than the ruiCreateInstance() and ruiGetState(), the ruiCreateConfig() function must be called in order to initialize the configuration.

ruiCreateConfig() creates a configuration for the SDK instance. A configuration is passed in a file, specified by configFilePath, productID, and appName. If two or more SDK instances, in the same process or in different processes, use the same values for these three parameters, then those SDK instances are bound together through a shared configuration. When multiple different executables are being used, such usage is generally not desirable nor recommended. Instead, each executable should use a different appName value.

The SDK has two communications modes: HTTPS or HTTP + AES-128 encryption. The mode is configured by protocol. When protocol is RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION or RUI_PROTOCOL_HTTPS_WITH_FALLBACK, the AES key must be supplied as a 128-bit (32 hex characters) hex-encoded string (aesKeyHex). When protocol is RUI_PROTOCOL_HTTPS, then aesKeyHex must be empty.

On first execution of a client application, no SDK configuration file will exist. This situation is detected by the SDK and will result in a New Registration message to the Server at ruiStartSDK(). Once the configuration is received from the Server, the SDK writes the configuration file, that is then used for subsequent client application executions.

ruiCreateConfig() must be called before most other APIs and must only be successfully called once.

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

ruiCreateConfig()

RUIRESULT ruiCreateConfig(RUIINSTANCE* ruiInstance, const char* configFilePath, const char* productID, const char* appName, const char* serverURL, int32_t protocol, const char* aesKeyHex, bool multiSessionEnabled, bool reachOutOnAutoSync)

Parameters

The ruiCreateConfig() function has the following parameters.

ruiCreateConfig() Parameters

Parameter

Description

ruiInstance (RUIINSTANCE*)

Pointer to the Usage Intelligence instance created via ruiCreateInstance()

configFilePath (const char*)

The directory to use for the SDK instance’s configuration file. Cannot be empty; must exist and be writable.

productID (const char*)

 

appName (const char*)

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:

What is the purpose of the appName parameter when creating config in the SDK? 

serverURL (const char*)

The URL to use for New Registrations. Subsequent communications from the SDK will either use this URL or the URL supplied by the Server. Cannot be empty. Cannot have a protocol prefix (e.g., no http:// or https://).

This URL is generated automatically on account creation and is used by the SDK to communicate with the Usage Intelligence server. You can get this URL from the Developer Zone once you login to the Usage Intelligence dashboard.

protocol (int32_t)

Indicates whether HTTP + AES, HTTPS with fall-back to HTTP + AES, or HTTPS only is used to communicate with the Server. Valid values are:

RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION 
RUI_PROTOCOL_HTTPS_WITH_FALLBACK 
RUI_PROTOCOL_HTTPS 

aesKeyHex (const char*)

AES Key to use when protocol includes encryption (RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION or RUI_PROTOCOL_HTTPS_WITH_FALLBACK); 32 hex chars (16 bytes, 128 bit) key.

multiSessionEnabled (bool)

Indicates whether or not the client will explicitly manage sessionIDs via ruiStartSession() and ruiStopSession(), and supply those sessionIDs to the various event tracking APIs.

reachOutOnAutoSync (bool)

Indicates whether or not a ReachOut should be requested as part of each SDK Automatic Sync.

A ReachOut request will be made only if a ReachOut handler has been set by registering the default graphical handler (ruiCreateInstance()) or a custom handler (ruiSetReachOutHandler()). This value may be changed at runtime using the call ruiSetReachOutOnAutoSync().

Returns

The ruiCreateConfig() function returns one of the return status constants below.

ruiCreateConfig() Returns

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_PERMANENTLY_DISABLED

The 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 white space, 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 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's not.

RUI_INVALID_AES_KEY_LENGTH

The AES Key is not the expected length (32 hex chars).

RUI_INVALID_AES_KEY_FORMAT

The AES Key is not valid hex encoding.

Code Example

The following example shows how to initialize the Usage Intelligence configuration:

// ruiCreateConfig example

bool useDefaultReachOutHandler = false;

 

RUIINSTANCE* mySDK = ruiCreateInstance(useDefaultReachOutHandler);

 

char* myPath = "PATH-TO-YOUR-CONFIG-FILE";

char* myURL = "CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";

char* myProductId = "INSERT-YOUR-PROD-ID";

char* myAppName = "MyApplication";

char* myKey = "0123456789abcdeffedcba9876543210";

bool multiSessionEnabled = false;

bool reachOutOnAutoSync = false;

 

RUIRESULT result = ruiCreateConfig(mySDK, myPath, myProductId, myAppName, myURL, RUN_PROTOCOL_HTTP_PLUS_ENCRYPTION, myKey, multiSessionEnabled, reachOutOnAutoSync);