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.
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.
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*) |
The Revenera-supplied product ID for this client; 10 digits. |
|||||||||
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:
|
|||||||||
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.
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);