Error handling

Fatal errors happening in the Qt Quick Ultralite library are reported through an API that can be implemented in application code. This API can be used to write a custom log message or store the error event. The implementation can not interact with the GUI anymore and is supposed to finally reboot the device or do something comparable.

Warning: The error handler must not return because the whole software stack is already in an invalid state.

The Qt Quick Ultralite library provides a default implementation that is used in the case when there is no implementation provided by the application.

The default error handler prints error report to Qul::Platform::PlatformContext::consoleWrite in the following format:

Qt for MCUs error: <errorRange>:<errorString>:<errorCode>, line: <lineNumber>, params: <param1>, <param2>, <param3>.
  • errorRange - Area/module related to the error. For example, Core, Platform, or Custom.
  • errorString - String describing the error code constant, but without the QulError_ prefix. It will be empty on release builds.
  • errorCode - Numeric value of the QulError.
  • lineNumber - Line number where the error occurred.
  • param1, param2, and param3 - Integer values providing additional information about the error.

The default handler halts the program after printing the error message, and enters an infinite loop to save the backtrace for debugging.

QulError provides a list of error codes reported by the Qt Quick Ultralite.

Note: Some of the error codes are only available in debug build. To enable all error checks, Qt Quick Ultralite Core and Platform needs to be rebuilt in debug build config.

Reporting custom errors

An error is reported with Qul::PlatformInterface::error. Assertion statement is done with QUL_ASSERT which calls Qul::PlatformInterface::error in case the expression is evaluated as false.

Qt Quick Ultralite reserves error code values from Core and Platform range. Custom error codes start from value QulError_Custom + 1.

enum CustomErrorCodes { CustomError_Foo = QulError_Custom + 1, CustomError_Bar };

Optional information can be provided with integer parameters param1, param2 and param3. The following example tests that someValue is bigger than 5. In case the assert fails, the actual value of someValue is shown via param1.

uint8_t someValue = 6;
QUL_ASSERT(someValue > 5, static_cast<QulError>(CustomError_Bar), someValue);

Setting a custom error handler

Custom error handler is set with Qul::setErrorHandler.

Available under certain Qt licenses.
Find out more.