1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page extending-qtivi.html
\title Extending Qt IVI
\section1 Introduction
Qt IVI provides a pattern for extending Qt with more features in a way that suites the
automotive use-case.
A key aspect is the separation between the frontend that defines the API, from the
backend that implements the functionality. This separation makes it possible to have
multiple implementations of the same API which can be used to interface various hardware
configurations, but also to provide stubbed or simulated implementations for early
development and testing purposes.
\section1 The Big Picture
Qt IVI consists of three types of building blocks. The core module provides base classes
and common code for all the more specific modules and API definitions like a climate API
or a mediaplayer API. Each of these APIs is the second building block called \e Feature,
which defines the API used by the application developers. The last block consists of a
backend interface and one or more \e Backends implementing it to either connect to the
underlying vehicle or do a simulation of it.
\section2 Features
A feature is a set of classes for working with a specific function. It defines the interface
towards application developers, but it does not implement the complete functionality. Instead, it
defines a backend interface to be implemented by a backend providing the actual function.
For easy deployment, Qt IVI extensions should be built as Qt modules. This makes it easy to
install and find headers, shared libraries, and plugin modules from app projects.
By using the module system the developer can easily enable the inclusion of his
module in the following way:
\code
QT += <module>
\endcode
In addition, your module is properly set up to work with cmake, qdoc, and auto test."
\code
make tests
\endcode
When creating a new Qt IVI module, it is recommended that you pick a name such as
\e {OemFeatureName}, where \e {Oem} is the name of the car maker or platform owner, and
\e {FeatureName} is the name of the feature(s) of the module. In addition to the name, a reverse
domain name prefix is needed for prefixing backend interface names, for example \e {com.example}
Features are based on the QIviAbstractFeature base class, or QIviAbstractZonedFeature for
zoned features. These classes provide the basic functions expected by users, e.g. backend
loading.
Features define the backend interface to be implemented by the backends providing the
functionality. The backend interface is commonly based on the QObject class. It is important
to keep this API as unbiased as possible, as there might be multiple backend implementations
relying on different technological solutions.
Some key rules to keep in mind are:
\list
\li Keep everything asynchronous to avoid blocking the main loop.
\li Avoid call-to-signal sequences and try to keep signals independent from calls, For example,
when a value change is signalled, it must not be due to a call to change the value from
the feature (and visa versa). In other words a call to change a value is not required to always
result in a value changed signal.
\li Avoid stateful APIs whenever possible as the backend may be replaced at any time.
\endlist
It is common to provide a stubbed backend implementation and a testing backend with each
feature.
\section2 Backends
A backend class is derived from the (commonly QObject-derived) backend interface class specified
by a feature. Instances of the backend class are called \e {service objects}.
Backends are implemented as an ordinary Qt C++ plugin project that depends on
\l {QtIviCore}{Qt IVI Core} and the corresponding feature module.
The backends are loaded by Qt IVI Core when the features request them. Each backend has to provide
a Qt IVI plugin that exposes a \e factory to the Core. This is what is used to load and create
backends. The plugin interface is called QIviServiceInterface.
\section2 Service Manager
In most cases, the backend loading is handed over to the Qt IVI Core, however, QIviServiceManager
can be used in this case to manually search for plugins with a specific BackendInterface. The
discovery and loading of the backends takes place in this class.
The QIviServiceManager class can also be used to register backends which are part of the same
application and shouldn’t go into a plugin. This is especially useful for autotest as you need
to control the backend and the feature at the same time.
\section1 Common Practices
The reference APIs provided as a part of Qt IVI introduce some common concepts. If
implementing the same functionality, it is recommended to use these already defined patterns and
it is encouraged to add API additions back to the Qt IVI repository to create more common ground
for future APIs.
*/
|
