Introduction

This example shows how to generate a Middleware API, a Middleware Backend, and the corresponding Middleware Service using the Qt IVI Generator. The communication between the backend and the service is done with QtRemoteObjects as the IPC.

We use a single QFace IDL file to generate:

• a shared library with the front-end code
• a backend plugin that implements a client to connect to the server
• a server that runs the actual backend logic in a separate server process
• a demo application that connects to the server and provides a UI to use the service

In addition to the generated C++ code, the backend plugin and the server also contain an intermediate .rep file that is further processed by the replica compiler to produce the source and replica classes.

Walkthrough

The IDL file used in the example represents an imaginary remote service for processing data. It contains a single interface with one property and one method.

First, we need to define which module we want to describe. The module acts as a namespace, because the IDL file can contain multiple interfaces.

module Example.IVI.Remote 1.0;

The most important part is the definition of the interface.

@config: { qml_type: "UiProcessingService" }
interface ProcessingService {

    string lastMessage;

    int process(string data);
}

In this case, we define an interface named ProcessingService with one property and one method. Every property and method definition needs to contain at least a type and a name. Most of the basic types are built-in and can be found in the QFace IDL Syntax.

Frontend library

Next, we use the IVI Generator to generate a shared library containing a C++ implementation of our module and its interface; particularly the frontend template. This template generates a class derived from QIviAbstractFeature, that includes all of the specified properties. The generated library uses the Dynamic Backend System from QtIviCore, consequently providing an easy way to change how the behavior is implemented.

To call the autogenerator for our shared library, the qmake project file needs to use the ivigenerator qmake feature:

CONFIG += ivigenerator
QFACE_SOURCES = ../example-ivi-remote.qface

By adding ivigenerator to the CONFIG variable, the ivigenerator feature file is loaded and interprets the QFACE_SOURCES variable, similar to the SOURCES variable in regular qmake projects. However, activating the qmake feature via the CONFIG variable has one disadvantage: if the feature is not available, no errors are reported. We recommend using the following additional code to report errors:

QT_FOR_CONFIG += ivicore
!qtConfig(ivigenerator): error("No ivigenerator available")

The remaining part of the project file is a normal library setup that works on Linux, macOS, and Windows.

QtRemoteObjects Backend Plugin

As mentioned above, the frontend library uses the Dynamic Backend System. This means that for the library to provide some functionality, we also need a backend plugin. The generated plugin here works as a client that connects to the server using Qt Remote Objects. The qmake integration works in the same way, but it uses the QFACE_FORMAT variable to tell the ivigenerator to use a different generation template, backend_qtro:

CONFIG += ivigenerator plugin
QFACE_FORMAT = backend_qtro
QFACE_SOURCES = ../example-ivi-remote.qface
PLUGIN_TYPE = qtivi
PLUGIN_CLASS_NAME = RemoteClientQtROPlugin

The generated backend plugin code is usable as is, and doesn't require any further change. As we want to generate a plugin instead of a plain library, we need to instruct qmake to do so by adding plugin to the CONFIG variable. For the plugin to compile correctly it needs to get the backend interface header from the previously created library. But this header is also generated, so it's not part of our source tree, but part of the build tree. To provide the backend interface header, we add it to the include path using the following construct:

INCLUDEPATH += $$OUT_PWD/../frontend

Most of the code in the backend plugin is generated by the IVI Generator, but some of it is generated by the Qt's Remote Object Compiler, repc. To achieve this, the IVI Generator produces an intermediate .repc file that's further processed by the repc compiler. This compiler is called via the generated .pri file, found in the build directory. Notice that you have to call qmake on the project, at least once to have the generated files available.

Our application doesn't know about the existence of our backend plugin, so we need to put this plugin in a folder where the application typically looks for plugins. By default, Qt either searches in the plugins folder within its installation directory or in the application's current working directory. For QtIvi plugins to be found, they need to be provided within a qtivi sub-folder. Add the following line to the backend project file, as follows:

DESTDIR = ../qtivi

RemoteObjects Server

The server is an independent, GUI-less application that contains the backend's business logic, and we need to write most of its implementation. Nevertheless, the generator produces some code to simplify the development. We can generate server side code by using the IVI Generator with the server_qtro template:

TEMPLATE = app
QT -= gui
CONFIG += c++11 ivigenerator
...
QFACE_FORMAT = server_qtro
QFACE_SOURCES = ../example-ivi-remote.qface

To use the generated remote source, we need to inherit from one of the classes defined in the generated rep_processingservice_source.h file. In this example, we implement our server's logic in the ProcessingService class and use the ProcessingServiceSimpleSource as the base class:

// server_qtro/processingservice.h
#include "rep_processingservice_source.h"

class ProcessingService : public ProcessingServiceSimpleSource
{
public:
    ProcessingService();

    QVariant process(const QString & data) override;
};

Note that the base class already has the definitions for property accessors, but any custom method or slot needs to be overridden and defined. Our implementation of the process function merely counts and returns the length of the data passed and updates the lastMessage property:

// server_qtro/processingservice.cpp
ProcessingService::ProcessingService()
{
    setLastMessage(QStringLiteral("Service online."));
}

QVariant ProcessingService::process(const QString & data)
{
    setLastMessage(QStringLiteral("Processed data \'%1\'").arg(data));
    return data.length();
}

To make the ProcessingService class accessible remotely, we need to share it via the QRemoteObjectNode::enableRemoting() function. The Core class generated provides a preconfigured instance of a remotenode that is used for the remoting. For the plugin to connect to the right object, use an identifier in the format "ModuleName.InterfaceName", which in our case is "Example.IVI.Remote.ProcessingService". All this is done in the main() function, along with the start of the main event loop:

// server_qtro/main.cpp
#include <QCoreApplication>

#include "processingservice.h"
#include "core.h"

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);

    ProcessingService service;
    Core::instance()->host()->enableRemoting(&service,QStringLiteral("Example.IVI.Remote.ProcessingService"));

    return app.exec();
}

This is all you need to do to implement a service that is accessible remotely; use the properties as usual and provide the method implementations. The QtRemoteObjects library takes care of the communication.

Demo Client Application

The demo application presents a simple QML GUI to use the remote service over the generated interface.

As we do not provide a QML plugin, the application needs to link to the generated frontend library and call the RemoteModule::registerTypes and RemoteModule::registerQmlTypes methods that are generated in the module singleton to register all autogenerated interfaces and types with the QML engine.

In our QML application, we still need to import the module using the same module URI which is used in the QFace file. Afterwards the interface can be instantiated like any other QML item.

// demo/main.qml
import Example.IVI.Remote 1.0

Window {
    visible: true
    width: 640
    height: 480
    title: qsTr("QtIVI Remote example")

    UiProcessingService {
        id: processingService
    }
...

Every method call that is made through a generated API, is asynchronous. This means that instead of directly returning a return value, a QIviPendingReply object is returned. Using the QIviPendingReply::then() method on the returned object, we may assign callbacks to it that are called when the method call has been successfully finished; or if it has failed.

// demo/main.qml
Button {
    text: "Process"

    onClicked: processingService.process(inputField.text).then(
        function(result) { //success callback
            resultLabel.text = result
        },
        function() { //failure callback
            resultLabel.text = "failed"
        } )
}

In case of properties, we use bindings as usual:

// demo/main.qml
Row {
    Text { text: "Last message: " }
    Text {
        id: serverMessage
        text: processingService.lastMessage
    }
}

Running the Example

To see the demo's entire functionality, run both the server and the demo application simultaneously. You may leave the server running and restart the application, or vice versa, to see that the reconnection works. Run the demo application alone without the server running, to test how the remote method call fails when there is no connection.

Example project @ code.qt.io