/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** 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 position-plugin-gypsy.html
\title Qt Positioning Gypsy plugin
\ingroup QtPositioning-plugins

\brief Uses the Gypsy daemon to provide satellite information

\section1 Overview

The plugin is an interface to the \l {Gypsy daemon}. It requires the daemon
to be installed and running on the system to function.

The plugin uses D-Bus and GLib to connect to GPS device and provide satellite
information.

Currently the plugin \e {does not} provide positioning information.

The plugin can be loaded using provider name \b gypsy.

\section1 Parameters

The following table lists parameters that \e can be passed to the gypsy
plugin.

\table
\header
    \li Parameter
    \li Description
\row
    \li deviceName
    \li The name of the device (or path to the device file) that will be used
        to provide satellite information. The typical values can be
        \c {/dev/ttyUSB0} or \c {/dev/ttyACM0}.
\row
    \li gconfKey
    \li The key that will be used to extract device name from the GConf
        configuration system.
\endtable

The plugin supports two ways of specifying the device name:
\list
    \li Specify the device name directly with the \e deviceName plugin
        parameter.
    \li Specify the configuration key using \e gconfKey plugin parameter and
        extract the device name from the GConf configuration system. This
        approach is useful when the device name is already specified for some
        other GConf-based application.
\endlist

By default, when none of the parameters is specified, the plugin will try to
extract the device name from the GConf configuration system using the following
hardcoded key:

\badcode
/apps/geoclue/master/org.freedesktop.Geoclue.GPSDevice
\endcode

\section2 Using GConf to set parameters

To specify a value for a key in the GConf configuration system, use
\e {gconftool-2} as follows:

\badcode
gconftool-2 -t string -s /apps/geoclue/master/org.freedesktop.Geoclue.GPSDevice /dev/ttyUSB0
\endcode

\section1 Usage example

The following examples show how to create a \b gypsy satellite info source
from C++.

Specifying device name directly:

\code
QVariantMap parameters;
parameters["deviceName"] = "/dev/ttyACM0";
QGeoSatelliteInfoSource *source = QGeoSatelliteInfoSource::createSource("gypsy", parameters, this);
\endcode

Using GConf key:

\code
QVariantMap parameters;
parameters["gconfKey"] = "/apps/myapp/mykey";
QGeoSatelliteInfoSource *source = QGeoSatelliteInfoSource::createSource("gypsy", parameters, this);
\endcode

*/
