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.
RUIRESULT ruiSync(RUIINSTANCE* ruiInstance, bool getReachOut)
Parameters
The ruiSync() function has the following parameters.
|
Parameter |
Description |
|
ruiInstance (RUIINSTANCE*) |
Pointer to the RUI 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.
|
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. |