If every connection is established, no callbacks are called and no actions are taken.
If there is problem with the server connection, the client will try to reconnect to the server and re-checkout the feature, and the status will be passed to the callback functions. The callback functions let you monitor various scenarios, such as which licenses are taken by other clients during network connection outages. In such cases, you could set flags or otherwise notify parts of your application that some licenses have been lost. Note that you do not necessarily need to set up all of the callback functions, but instead use only those needed to modify the default behavior.
The heartbeat callback functions can be enabled with LMX_SetOption(). Note: Attempting to call API functions from the heartbeat callback functions will return the error LMX_API_NOT_REENTRANT. This includes calling LMX_GetErrorMessage ; however, you can call LMX_GetErrorMessageSimple instead.
Possible callback functions are:
Name | Status Information Returned |
|---|---|
HEARTBEAT_CONNECTION_LOST_FUNCTION | Connection with license server was lost. |
HEARTBEAT_RETRY_FEATURE_FUNCTION | Reconnection with license server succeeded. Re-attempt to checkout feature from license server. |
HEARTBEAT_CHECKOUT_FAILURE_FUNCTION | License lost; could not be regained from license server. |
HEARTBEAT_CHECKOUT_SUCCESS_FUNCTION | License retained successfully. |
HEARTBEAT_EXIT_FUNCTION | The automatic heartbeats thread calls this callback function when it has given up reconnecting to the license server. When using this callback, ensure you set a proper exit flag during the callback and then shut down or otherwise cease functionality of the application. |
The callback functions work as follows:
In case of failure, the HEARTBEAT_CONNECTION_LOST_FUNCTION callback is always called. At the next heartbeat, if the connection is lost, the client tries to reconnect to the license server from which the feature was checked out. The number of reconnection attempts can be specified by setting the LMX_OPT_AUTOMATIC_HEARTBEATS_ATTEMPTS option.
After the last unsuccessful attempt to reconnect to the same server, the client will then try to connect to other servers. When the client successfully reconnects to the same server or a different server, the HEARTBEAT_RETRY_FEATURE_FUNCTION callback is called, and the client attempts to re-checkout the feature. The re-checkout will succeed only if the feature that is being renewed has a version equal to or less than the version of the feature that is currently being served by the server. To specify that the feature version being renewed must exactly match the feature version currently being served by the server, you must enable LMX_OPT_EXACT_VERSION.
The HEARTBEAT_RETRY_FEATURE_FUNCTION callback may be called many times, because LM-X will not stop retrying the checkout until all possible license servers have been tried. Every HEARTBEAT_RETRY_FEATURE_FUNCTION is followed by either HEARTBEAT_CHECKOUT_SUCCESS_FUNCTION or HEARTBEAT_CHECKOUT_FAILURE_FUNCTION.
- If re-checkout succeeds, the HEARTBEAT_CHECKOUT_SUCCESS_FUNCTION callback is called.
- If re-checkout fails (for example, when there are no licenses left for checkout), HEARTBEAT_CHECKOUT_FAILURE_FUNCTION is called.
- The HEARTBEAT_EXIT_FUNCTION callback is called only if the heartbeat count is exhausted.
Examples
The following examples describe callback function behavior when heartbeats are lost.
Available Servers | Client Action | Type of Heartbeats Implemented | Callback Function Behavior When Connection Is Lost |
|---|---|---|---|
S1 | CHECKOUT feature from S1 | Automatic | (LMX_OPT_AUTOMATIC_HEARTBEAT_ATTEMPTS set to 3) |
S1, S2, S3 | CHECKOUT feature from S1 | Automatic | (LMX_OPT_AUTOMATIC_HEARTBEAT_ATTEMPTS set to 5) |
S1, S2, S3 | CHECKOUT feature from S1 | Manual | (S1 goes down) |
S1 and S2 | CHECKOUT features A and B from S1 CHECKOUT feature C from S2 | Automatic | (LMX_OPT_AUTOMATIC_HEARTBEATS_ATTEMPTS set to 3) |
S1 and S2 | CHECKOUT feature from S1 | Automatic | (LMX_OPT_AUTOMATIC_HEARTBEATS_ATTEMPTS set to 3) |