Automated Message Retrieval

The Usage Intelligence V5 SDK provides a default, automated ReachOut handler that works on Windows and macOS. Developers can override this handler by implementing the ReachOut handler functions with their own code and providing these handler functions to the the ruiSetReachOutHandler() function. See the ruiSDKC.h file for details on the functions required to support custom ReachOut. The three functions include:

Functions Required to Support Custom ReachOut

Function	Description
void (*RUIReachOutHandler)(void* arg, const char* width, const char* height, int32_t position, const char* message)	Handles the ReachOut message. The parameters are: • width—Width of the window as configured in the ReachOut campaign. Value will be suffixed by P for pixels or % for percentage. • height—Height of the window as configured in the ReachOut campaign. Value will be suffixed by P for pixels or % for percentage. • position—Position where the window should be displayed (1 = top-left, 2 = top-center, 3 = top-right, 4 = middle-left, 5 = middle-center, 6 = middle right, 7 = bottom-left, 8 = bottom-center, 9 = bottom-right). • message—URL to display.
int (*RUIReachOutGetReadyForNext)(void* arg)	To handle getting the status of whether the handler is ready for the next ReachOut message. Returns 0 for not ready, non-zero for ready.
void (RUI_CALLBACK_LINKAGE *RUIReachOutCloser)(void* arg)	Called when the SDK is stopping or shutting down.

The ruiSetReachOutHandler() function sets a custom ReachOut handler. Any previously registered handler, including the default graphical ReachOut handler that may have been registered (ruiCreateInstance()). If handler is NULL, then all parameters are considered to be NULL. Setting a handler to NULL effectively removes the current handler, if any, without setting a new handler.

ruiSetReachOutHandler() can be called more than once.

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

ruiSetReachOutHandler()

RUIRESULT ruiSetReachOutHandler(RUIINSTANCE* ruiInstance, RUIREACHOUTHANDLER handler, RUIREACHOUTCLOSER closer, RUIREACHOUTREADYFORNEXT getReadyForNext, void* arg)

Parameters

The ruiSetReachOutHandler() function has the following parameters.

ruiSetReachOutHandler() Parameters

Parameter	Description
ruiInstance (RUIINSTANCE*)	Pointer to the Usage Intelligence instance created via ruiCreateInstance().
handler (RUIREACHOUTHANDLER)	The function to be called when a ReachOut is received from the Server.
closer (RUIREACHOUTCLOSER)	The function to be called when the SDK is shutting down.
getReadyForNext (RUIREACHOUTREADYFORNEXT)	The function to be called when the SDK is checking to see if the handler is ready for a new ReachOut message.
arg (void*)	Data to be passed to handler function and closer function; provides the client a self-managed handle.

Returns

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

ruiSetReachOutHandler() Returns

Parameter	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_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_SDK_ALREADY_STARTED	The SDK has already been successfully started.
RUI_SDK_ALREADY_STOPPED	SDK has already been successfully stopped.