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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example declarative-sfw-dialer
\title Service Framework using QML Example
\section1 Execution
Qt Creator is recommended and easiest way to compile, deploy and execute this application.
The following steps have to be done manually if this application is to be executed in Qt
Simulator:
\list
\o Plugin based services (\c landlinedialer and \c voipdialer) must be manually copied
to the same directory as the \c qmldialer executable.
IPC-based services (\c remotedialer in this example) are not supported by Qt Simulator.
\o A new \c xmldata folder must be created in the same directory as \c qmldialer
executable, and the xml files for service plugins (landlinedialerservice.xml and
voipdialerservice.xml) must be copied to that folder.
\endlist
\section1 Explanation
This example should demonstrate how to use the Service Framework to
access a list of services in a QML context. A library plugin provides QML with elements
that can reference a single service or a list of services, called 'Service' and
'ServiceList' respectively.
An example that demonstrates how to connect to a single service object to
implement a simple note taking application can be found \l{declarative-sfw-notes}{here}.
\target guidesign
The GUI looks like following picture:
\image DialerServiceGUI.png "GUI"
The following steps outline how to make a QML based application using the Service Framework technology.
It is assumed that QtMobility has been successfully built and environment variables have been set
as per \l {Installation Guide}.
\section2 Service Framework in QML
To included the Service Framework QML plugin to our QML file we need to import it as follows:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialerList.qml 4
\section2 The Services
The services are implemented in a shared library and can be register in the service framework.
After the service is registered it can be used in different applications.
In our case we'll access the services over an application that is based on QML scripting.
We will be able to change between different services and call their properties,
receiving their signals and so forth.
In this example we've implemented 2 services called
Landdialer and Voipdialer.
You can find the projects for those services in:
declarative-sfw-dialer\\landlinedialer and declarative-sfw-dialer\\voipdialer.
Those projects will create a shared library in each case.
If the library needs to be available over the Service Framework,
we need to register the library.
As you can see we register the services using a xml file.
This xml file basically contains all information to register the shared library in the
Service Framework environment.
For more information please read more about the Qt Service Framework
\l {service-frameworks.html#adding-and-removing-of-services}{XML Format}
The QServiceManager creates an instance of a services over a QServicePluginInterface.
For each services we provide a Plugin.
\snippet declarative-sfw-dialer/voipdialer/voipdialerplugin.h 0
The Q_INTERFACES macro tells Qt which interfaces the class implements.
Both seviceplugins needs to implement the QServicePluginInterface.
In our case we only need to overwrite the virtual function createInstance.
\snippet declarative-sfw-dialer/voipdialer/voipdialerplugin.cpp 0
As you can see the createInstance function create the appropriate dialer object
and returns it.
The Q_EXPORT_PLUGIN2 macro provides the necessary implementation for a plugin.
See \l{How to Create Qt Plugins} for more details.
The last thing we need to provide in our services are
the states, properties, signals and slots that we
want to access in out QML script later.
\target voipdialer_h_0
\snippet declarative-sfw-dialer/voipdialer/voipdialer.h 0
\section2 Service access on the QML site
The QML elements are implemented in 4 different qml scripting files
\l {guidesign}{ see GUI design}.
The first step is to use our ServiceWrapperList to specify the interface and minimum version (optional) through QML item
context, which will produce a list of ServiceWrapper objects.
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialerList.qml 5
In the DialerList.qml file the services property is assigned to the ListView model property.
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialerList.qml 0
To show the items of the model property we need to create a delegate component and assign it to the ListView
Delegate property:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialerList.qml 1
In this component you can define how you want to draw one ListView item.
You can access inside of this component the current ListWiew item by using the variable modelData.
In our example we are using two text lines. Furthermore we can define whats happening if we click
on a ListView item by using the MouseRegion.
\target DialerList_qml_2
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialerList.qml 2
Another component can be created for highliting a list item:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialerList.qml 3
\section2 Service signals and function calls on the QML site
In declarative-sfw-dialer.qml we define a control named DialScreen and implement
the function onDial and onHangup.
As you can see in the onDial event we call the service function dialNumber and
the onHangup calls hangup.
Both function are implemented in the service \l {voipdialer_h_0} { (see voipdialer header file).}
\snippet declarative-sfw-dialer/declarative-sfw-dialer/declarative-sfw-dialer.qml 0
In DialScreen.qml the dial and the hangup signals are defined.
The hangup signal will be emitted if the HangUpButton was clicked:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialScreen.qml 1
The dial signal will be emitted if the CallButton was clicked:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/content-sfw-dialer/DialScreen.qml 2
Now we need to connect the stateChanged signal form the services with an event handler on the QML site.
This is done in our main declarative file:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/declarative-sfw-dialer.qml 1
The DialScreen.currentDialer is assigned during a ListView item click in the
\l {DialerList_qml_2}{ ServiceList.qml file}.
\section1 Deployment of services
In this example application services are registered by QServiceManager::addService() method and
this is a reason why XML service description files are copied to /xmldata folder under
/bin folder of declarative-sfw-dialer application.
landlinedialer.pro:
\code
xml.path = /opt/declarative-sfw-dialer/bin/xmldata
xml.files = landlinedialerservice.xml
INSTALLS += xml
\endcode
qmldialer.cpp:
\snippet declarative-sfw-dialer/declarative-sfw-dialer/qmldialer.cpp 0
Note: Application does not need register services by itself in Symbian because automatic registration
system is doing this on behalf of the application. More details in next chapter.
\section2 Deployment in Symbian
Automatic registration is used as registration method in this example application for application services.
See more details
about \l {service-frameworks.html#automatic-registration}{Automatic Registration}.
landlinedialer.pro:
\code
xmlautoimport.sources = landlinedialerservice.xml
xmlautoimport.path = /private/2002AC7F/import/
DEPLOYMENT += xmlautoimport
\endcode
Shared libraries (service plug-ins) are deployed same way as other Qt plug-ins in Symbian.
\l {http://www.developer.nokia.com/Community/Wiki/CS001391_-_Implementing_the_Qt_plug-in_interface}{See more details.}
landlinedialer.pro:
\code
load(data_caging_paths)
pluginDep.sources = serviceframework_landlinedialerservice.dll
pluginDep.path = $$QT_PLUGINS_BASE_DIR
DEPLOYMENT += pluginDep
\endcode
\section2 Deployment in MeeGo 1.2 Harmattan
In addition of general registration, explained in \l {Deployment of services}{"Deployment of services" chapter,} service applications must be also registered to D-Bus for an autostarting if remote IPC-based service is used (remotedialer in this example). This can be done by defining .conf and .service files and adding
following lines to the .pro file.
remotedialer.pro:
\code
contains(MEEGO_EDITION,harmattan) {
remotedialer_conf.files = remotedialer.conf
remotedialer_conf.path = /etc/dbus-1/session.d/
remotedialer_service.files = com.nokia.qt.examples.dialer.service
remotedialer_service.path = /usr/share/dbus-1/services/
target.path = /opt/remotedialer/bin
INSTALLS += target remotedialer_conf remotedialer_service
}
\endcode
remotedialer.conf:
\code
<busconfig>
<policy context="default">
<allow own="com.nokia.qt.examples.Dialer"/>
</policy>
</busconfig>
\endcode
com.nokia.qt.examples.dialer.service:
\code
[D-BUS Service]
Name=com.nokia.qtmobility.sfw.VoipDialer
Exec= /opt/remotedialer/bin/dialer_service
User=user
\endcode
Note: Service name defined in .service file must always start with \c com.nokia.qtmobility.sfw when
registering is done for a service framework.
In MeeGo 1.2 Harmattan target dialer services can be pre-registered also by service framework command line tool
but this option is not needed if services has been deployed as descriped above.
\list
\o ./servicefw add voipdialerservice.xml
\o ./servicefw add landlinedialerservice.xml
\o ./servicefw add remotedialerservice.xml
\o ./servicefw dbusservice removedialerservice.xml dialer_service
\endlist
These deployment commands will register the two plugin-based services as well as the remote
IPC-based service. The last line features the ability to create an autostarting file for
D-Bus if the platform supports the QtDBus module, typically available on Linux systems.
*/
|
