1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29\page qtpositioning-plugins.html
30\title Qt Positioning Plugins
31\brief Default Plugins and Implementing Qt Positioning plugins
32
33Qt Positioning provides the majority of its functionality through plugins.
34This document outlines how to develop a new position plugin.
35
36\section1 Default plugins
37Some plugins already ship with Qt. These are:
38
39\table
40    \row
41        \li \b android
42        \li Wraps Android positioning subsystem. Available only on Android.
43    \row
44        \li \b corelocation
45        \li Wraps iOS and macOS positioning subsystems. Available only on Apple platforms supporting corelocation.
46    \row
47        \li \b geoclue
48        \li Interfaces with \l{https://www.freedesktop.org/wiki/Software/GeoClue/}{GeoClue} v0.12. Requires GeoClue 0.12 to be present to function.
49    \row
50        \li \b geoclue2
51        \li Interfaces with \l{https://www.freedesktop.org/wiki/Software/GeoClue/}{GeoClue} v2. Requires GeoClue v2 to be present to function.
52    \row
53        \li \b gypsy
54        \li Interfaces with \l{https://gypsy.freedesktop.org/wiki/}{Gypsy} daemon. Requires Gypsy to be present to function.
55    \row
56        \li \b winrt
57        \li Wraps WinRT positioning subsystem. Available only on WinRT and Windows10.
58    \row
59        \li \b serialnmea
60        \li A \l {Qt Positioning Serial NMEA plugin}{Serial NMEA} backend that parses NMEA streams from a GPS receiver over a
61        serial link to provide position updates.
62    \row
63        \li \b positionpoll
64        \li A backend providing only area monitoring functionalities via polling on position updates.
65\endtable
66
67
68\section1 Plugin Description
69
70Each plugin is described by a json file. The json describes the plugins capabilities and
71version. Below is an example of a json file used by the postionpoll plugin:
72
73\quotefile ../../../plugins/position/positionpoll/plugin.json
74
75The entries have the following meaning:
76
77\table
78    \header
79        \li Key
80        \li Description
81    \row
82        \li Keys
83        \li The unique name/key of the plugin. Each position plugin must have a unique name.
84    \row
85        \li Provider
86        \li The provider name of the services. Multiple plugins may have the same name.
87            In such cases the Version string will be used to further distinguish the plugins.
88    \row
89        \li Position
90        \li Set to \c true if the plugin implements a \l QGeoPositionInfoSource.
91    \row
92        \li Satellite
93        \li Set to \c true if the plugin implements a \l QGeoSatelliteInfoSource.
94    \row
95        \li Monitor
96        \li Set to \c true if the plugin implements a \l QGeoAreaMonitorSource.
97    \row
98        \li Priority
99        \li The plugin priority. If multiple plugins have the same provider name, the plugin
100            with the higest priority will be used.
101\endtable
102
103\section1 Implementing Plugins
104
105A plugin implementer needs to subclass \l QGeoPositionInfoSourceFactory and override one or more of
106its functions. If a plugin does not support a specific feature the function should return 0 or
107utilize the default implementation.
108
109\list
110    \li \l QGeoPositionInfoSourceFactory::areaMonitor()
111    \li \l QGeoPositionInfoSourceFactory::positionInfoSource()
112    \li \l QGeoPositionInfoSourceFactory::satelliteInfoSource()
113\endlist
114*/
115