diff options
author | Assam Boudjelthia <assam.boudjelthia@qt.io> | 2020-04-07 14:29:09 +0300 |
---|---|---|
committer | Assam Boudjelthia <assam.boudjelthia@qt.io> | 2020-05-25 17:14:38 +0300 |
commit | 79f643e6f9f91015e18605854161e96ed12730a3 (patch) | |
tree | 9b67d23637cb51bf62ee3e92ed18c5ee51871e74 /examples/androidextras/services/serviceremoteobjects/doc/src | |
parent | 9dc12a9289d542fabed8a30ad347ed80e471f93b (diff) |
Add Android Service examples with Remote Objects
Additional service examples with communication using Qt Remote Objects.
Task-number: QTBUG-83038
Change-Id: I6451c816681e314bd4f47c8966c5d98cd225e64d
Reviewed-by: Ville Voutilainen <ville.voutilainen@qt.io>
(cherry picked from commit d560ad9f356e2f5912b0ebabde4c001efcb9b31f)
Diffstat (limited to 'examples/androidextras/services/serviceremoteobjects/doc/src')
-rw-r--r-- | examples/androidextras/services/serviceremoteobjects/doc/src/qtandroidextras-example-service-remoteobjects.qdoc | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/examples/androidextras/services/serviceremoteobjects/doc/src/qtandroidextras-example-service-remoteobjects.qdoc b/examples/androidextras/services/serviceremoteobjects/doc/src/qtandroidextras-example-service-remoteobjects.qdoc new file mode 100644 index 0000000..667f31b --- /dev/null +++ b/examples/androidextras/services/serviceremoteobjects/doc/src/qtandroidextras-example-service-remoteobjects.qdoc @@ -0,0 +1,183 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtAndroidExtras module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Android Service with Qt Remote Objects + \ingroup examples-qtandroidextras + \example services/serviceremoteobjects + \brief Demonstrates how to run an Android service in a separate process, + and how to communicate between the service process and the main process + using Qt Remote Objects. + + \image androidservices.png + + This example demonstrates how to create and run an Android service in + a separate process from the main application process, and then exchange data + between QML/C++ and the Java service using \l{Qt Remote Objects}. + + When clicking the \uicontrol {Send to Service} button, the name entered in the QML + view, Qt, in this case, is sent to the Android service. Then, the service + replies back with a message \c {Hello Qt} which is printed in the QML view. + + \include examples-run.qdocinc + + \section1 Create the Service + + To start a service in its own process, extend the \c QtService class for + your service. Extending \c QtService allows the service to load the necessary + Qt libraries used for Qt, like \l{Qt Remote Objects} libraries. + + Start by creating the Java service class. The following class extends \c QtService + and acts as your service entry point: + + \quotefromfile services/serviceremoteobjects/android/src/org/qtproject/example/qtandroidservice/QtAndroidService.java + \skipto package + \printuntil /^\}/ + + This class can have any logic you want using Java code. However, you don't need + any logic to communicate with Qt as that will be done using Qt Remote Objects. + + \section1 Manage the AndroidManifest.xml File + + To use the service, it must be declared in the \c AndroidManifest.xml + file as follows: + + \quotefromfile services/serviceremoteobjects/android/AndroidManifest.xml + \skipto <service + \printuntil </service> + + The important part of this service declaration is the \c lib_name part. + It will ensure that the service is run by the service's own lib file: + + \quotefromfile services/serviceremoteobjects/android/AndroidManifest.xml + \skipto android:value="service" + \printuntil android:value="service" + + \section1 Handle the Application Start + + To start the service, call the following function from the application's + \c main(): + + \quotefromfile services/serviceremoteobjects/main.cpp + \skipto startService + \printuntil /^\}/ + + \section1 Handle the Service Start + + \l{QAndroidService} is used to create the service process. For the service + to start from its own \c .so lib file, create a sub-project with the following + \c .pro file: + + \quotefromfile services/serviceremoteobjects/service.pro + \printuntil CONFIG + + \section1 Communication with Qt Remote Objects + + To use \l{Qt Remote Objects}, define a \c .rep file: + + \quotefromfile services/common/qtandroidservice.rep + \skipto class + \printuntil /^\}/ + + Define the \c .rep source file in the service project \c .pro: + + \quotefromfile services/serviceremoteobjects/service.pro + \skipto REPC_SOURCE + \printline REPC_SOURCE + + And in the application's \c .pro file: + + \quotefromfile services/serviceremoteobjects/serviceremoteobjectsclient.pro + \skipto REPC_REPLICA + \printline REPC_REPLICA + + Then define the class used by Qt Remote Objects, which has a + \c sendToService() slot and a \c messageFromService() signal: + + \quotefromfile services/common/qtandroidservice_ro.h + \skipto include + \printuntil /^\};/ + + Include the class in the previous snippet in \c main.cpp: + + \quotefromfile services/serviceremoteobjects/main.cpp + \skipto _replica.h + \printline _replica.h + + Now, in the service's \c service_main.cpp, create the \l{QRemoteObjectHost} + node and start \l{QAndroidService}: + + \quotefromfile services/serviceremoteobjects/service_main.cpp + \skipto include + \printuntil /^\}/ + + In the application's \c main.cpp, create the client node and connect it + to the source node created in the service and connect it to the QML view: + + \quotefromfile services/serviceremoteobjects/main.cpp + \skipto QRemoteObjectNode + \printuntil sendToService + + Then, add a \l Connections element to watch for the incoming messages from + the service: + + \quotefromfile services/common/main.qml + \skipto Connections + \printuntil /^\ {4}\}/ + + And set the \c onClicked for the sending button to: + + \quotefromfile services/common/main.qml + \skipto onClicked + \printline onClicked + + \sa {Android Service with Qt Remote Objects - Same Lib File}, + {Android Services}, {Qt for Android}, {Qt Android Extras} +*/ |