Skip to content

Working with licenses🔗

Handling licensing errors🔗

When running HALCON with a runtime license and a dongle, HALCON regularly checks whether the dongle is still available. This check has no measurable impact on the performance of HALCON.

To be notified if the dongle was removed and a license error is imminent, applications can register a callback function with HALCON that will be called when HALCON detects that the dongle is no longer available. HALCON operators will fail with licensing errors after about two to four minutes after this callback fires. If the dongle is reinserted before this time, HALCON will continue to operate normally.

If you do not register a callback and the dongle becomes unavailable during runtime, HALCON operators will fail with a license error and will therefore not provide meaningful output parameters. Depending on your application, this might even lead to crashes. Therefore, handling errors from operators correctly or registering the callback to notify the user or shut down the application in a controlled way is highly recommended.

To register your own callback function, do the following:

  1. Use the following code in your application:
    void __stdcall MyLicenseRecheckFailedCallback(void *context, Herror error)
    {
      <Add your application-specific callback code here.>
    }
    
  2. Somewhere in your application startup code, add the following:
    HSetLicenseRecheckFailedCallback(MyLicenseRecheckFailedCallback,
                                    &MyLicenseRecheckFailedContext);
    
    MyLicenseRecheckFailedContext is a user-defined structure that you can use to pass extra information to your callback. If you do not need this, you can pass a NULL pointer instead.

Note

Callbacks are not chained – registering a callback will overwrite any previously registered callback.

To unregister a callback, call HSetLicenseRecheckFailedCallback with a NULL pointer as argument.

To check whether a license is available at all, you can use any operator at the beginning of your application and check the result.

Example

In your application, you might implement a proper licensing error handling like this:

Check for licensing errors in C
Herror error;
Htuple param, value;

create_tuple_s(&amp;param, &quot;version&quot;);
set_check(&quot;~give_error&quot;);
error = T_get_system(param, &amp;value);
destroy_tuple(value);
destroy_tuple(param);

if ((error &gt;= H_ERR_LIC_NO_LICENSE) &amp;&amp; (error &lt;= H_ERR_LAST_LIC_ERROR))
{
  /* Handle licensing error here. */
}
Check for licensing errors in C++
try
{
  HalconCpp::HTuple value = HalconCpp::HSystem::GetSystem(&quot;version&quot;);
}
catch (HalconCpp::HException &amp;exception)
{
  if (   (exception.ErrorCode() &gt;= H_ERR_LIC_NO_LICENSE)
      &amp;&amp; (exception.ErrorCode() &lt;= H_ERR_LAST_LIC_ERROR))
  {
    // Handle licensing error here.
  }
}

Returning floating licenses on Windows🔗

Applications using a HALCON floating license should return the license to the license server on exit so that it can be reused immediately. As socket communication is not possible during process termination, a process using HALCON cannot return floating licenses automatically on Windows by itself and requires the help of the license watchdog process hlwd.

Only if the license watchdog is not available, the process using HALCON must return the floating license before termination either by calling FinalizeHALCONLibrary() (see Terminating HALCON library) or by calling the HALCON operator set_system with the parameter 'return_license'.