Core

Fatal errors happening in Qt Quick Ultralite Core 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.

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:

Error: <description>
Qt for MCUs Core error: <errorString>:<errorCode>, line: <lineNumber>, arguments: <arg1>, <arg2>, <arg3>.

• errorString - String describing the error. It will be empty on release builds.
• errorCode - Numeric value of the error code.
• lineNumber - Line number where the error occurred.
• arg1, arg2, and arg3 - 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.

Some error codes are only available in debug builds. Rebuild Qt Quick Ultralite Core in debug build config to enable all error checks. In debug builds, use errorString to find the origin of the error.

Each error also has its own distinct numeric errorCode. In release builds, where errorString is empty, you can still use this number to trace back exactly which check failed.

Several checks can report the same error code. Such codes use arg1 as a subcode identifying which check failed, and put any further values in arg2 and arg3. Each of these codes has its own set of subcodes, and arg1 is 0 when no subcode applies. For every other error code, the values in arg1, arg2, and arg3 are specific to that code.

The description line above is written to the log at the point of failure, before either error handler runs. It is not included by default. Enable QUL_ASSERT_VERBOSE to add it to the report. A custom handler does not receive this line as a parameter.

Setting a custom error handler

Custom error handler is set with Qul::setErrorHandler.

Qul::initHardware();
Qul::setErrorHandler(customErrorHandler);
Qul::initPlatform();
Qul::Application app;

Optional information is provided with integer arguments arg1, arg2 and arg3.

#include <qul/error.h>

void customErrorHandler(unsigned int code, unsigned int lineNumber, int arg1, int arg2, int arg3)
{
    Qul::PlatformInterface::log("Error code: %u, line: %u, arguments: %i, %i, %i.\r\n",
                                code,
                                lineNumber,
                                arg1,
                                arg2,
                                arg3);

    while (1) {
    }; // The error handler must not return!
}

Platform

QUL_PLATFORM_ASSERT and QUL_PLATFORM_DEBUG_ASSERT report fatal errors from platform adaptation code, independently of Qt Quick Ultralite Core's own error reporting above. Both call Qul::Platform::PlatformContext::error, which a platform adaptation can reimplement to customize the behavior.

The default implementation prints:

Error: <description>
Qt for MCUs Platform error at <file>:<line>, arguments: <arg1>, <arg2>, <arg3>

The description line is not included by default. Enable QUL_PLATFORM_ASSERT_VERBOSE to include it in the report.

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