Forced Synchronization

Under normal conditions, you do not need to instruct the Usage Intelligence SDK when to synchronize with the cloud server, since this happens automatically and is triggered by application interaction with the API. In a typical runtime session, the SDK will always attempt to synchronize with the server at least once whenever the application calls ruiStartSDK(). For long running applications, the SDK will periodically sync with the server every 20 minutes.

For applications that require a more customized synchronization, the API also provides an option to request manual synchronization of all cached data. This is done by calling the ruiSync() function.

The ruiSync() function performs a manual synchronization with the Server. In normal operation, the SDK periodically performs automatic synchronizations with the Server. ruiSync() provides the client an ability to explicitly synchronize with the Server on demand. The manual synchronization can request a ReachOut with getReachOut.

Note:Similar to the parameter reachOutOnAutoSync (on function ruiCreateConfig()), the ReachOut will not be requested if there is no registered handler (ruiCreateInstance() and ruiSetReachOutHandler()).

ruiSync() can be called between ruiStartSDK() and ruiStopSDK() and can be called zero or more times.

Note: ruiSync() will not be successful if a New Registration is in progress (i.e. ruiCreateConfig() and ruiStartSDK()). A manual synchronization with the Server can be associated with ruiStopSDK().

ruiSync() is an asynchronous function returning immediately with further functionality executed on separate thread(s).

As explained in the previous section, this function is not normally required and should be avoided in most cases. Both the SDK and the Server can reject a ruiSync() request from occurring even if this is requested by the developer. This is done to prevent abuse and unnecessary server load if this function is called too frequently.

ruiSync()

RUIRESULT ruiSync(RUIINSTANCE* ruiInstance, bool getReachOut)

Parameters

The ruiSync() function has the following parameters.

ruiSync() Parameters

Parameter

Description

ruiInstance (RUIINSTANCE*)

Pointer to the Usage Intelligence instance created via ruiCreateInstance().

getReachout (bool)

This optional parameter instructs the server whether to send a ReachOut message during this particular sync if available.

Returns

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

ruiSync() Returns

Return

Description

RUI_OK

Synchronous functionality 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_SUSPENDED

The Server has instructed a temporary back-off.

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_CONFIG_NOT_CREATED

Configuration has not been successfully created.

RUI_SDK_NOT_STARTED

SDK has not been successfully started.

RUI_SDK_ALREADY_STOPPED

SDK has already been successfully stopped.

RUI_TIME_THRESHOLD_NOT_REACHED

The API call frequency threshold (set by the Server) has not been reached. Sync not allowed at this time.