qdeclarativesatellitesource.cpp

Go to the documentation of this file.

// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
 
#include "qdeclarativesatellitesource_p.h"
 
QT_BEGIN_NAMESPACE
 
/*!
    \qmltype SatelliteSource
    \inqmlmodule QtPositioning
    \since 6.5
    \brief The SatelliteSource class provides the satellite information.
 
    The SatelliteSource class provides information about satellites in use and
    satellites in view. This class is a QML representation of
    \l QGeoSatelliteInfoSource.
 
    Like its C++ equivalent, the class supports different plugins. Use the
    \l name property to specify the name of the plugin to be used, and provide
    \l {PluginParameter}s, if required. If the \l name property is not set,
    a default plugin will be used. See \l {Qt Positioning Plugins} for more
    information on the available plugins.
 
    Use the \l valid property to check the SatelliteSource state.
 
    Use the \l updateInterval property to indicate how often your application
    wants to receive the satellite information updates. The \l start(),
    \l stop() and \l update() methods can be used to control the operation
    of the SatelliteSource, as well as the \l active property, which when set
    is equivalent to calling \l start() or \l stop().
 
    When the SatelliteSource is active, satellite information updates can
    be retrieved using the \l satellitesInView and \l satellitesInUse
    properties.
 
    If an error happens during satellite information updates, use the
    \l sourceError property to get the actual error code.
 
    \section2 Example Usage
 
    The following example shows a SatelliteSource which is using the
    \l {Qt Positioning NMEA plugin}{NMEA} plugin to receive satellite
    information updates every second and print the amount of satellites
    in view and satellites in use to the console.
 
    \qml
    SatelliteSource {
        id: source
        name: "nmea"
        active: true
        updateInterval: 1000
        PluginParameter { name: "nmea.source"; value: "serial:/dev/ttyACM0" }
 
        onSatellitesInUseChanged: {
            console.log("Satellites in use:", source.satellitesInUse.length)
        }
        onSatellitesInViewChanged: {
            console.log("Satellites in view:", source.satellitesInView.length)
        }
    }
    \endqml
 
    \sa QGeoSatelliteInfoSource, PluginParameter, geoSatelliteInfo
*/
 
QDeclarativeSatelliteSource::QDeclarativeSatelliteSource()
    : m_active(0), m_componentComplete(0), m_parametersInitialized(0),
      m_startRequested(0), m_defaultSourceUsed(0), m_regularUpdates(0),
      m_singleUpdate(0), m_singleUpdateRequested(0)
{
}
 
QDeclarativeSatelliteSource::~QDeclarativeSatelliteSource()
{
    if (m_source)
        m_source->disconnect(this);
}
 
/*!
    \qmlproperty bool SatelliteSource::active
 
    This property indicates whether the satellite source is active.
    Setting this property to \c false equals calling \l stop, and
    setting this property to \c true equals calling \l start.
 
    \sa start, stop, update
*/
bool QDeclarativeSatelliteSource::isActive() const
{
    return m_active;
}
 
/*!
    \qmlproperty bool SatelliteSource::valid
    \readonly
 
    This property is \c true if the SatelliteSource object has acquired a valid
    backend plugin to provide data, and \c false otherwise.
 
    Applications should check this property to determine whether providing
    satellite information is available and enabled on the runtime platform,
    and react accordingly.
*/
bool QDeclarativeSatelliteSource::isValid() const
{
    return m_source != nullptr;
}
 
/*!
    \qmlproperty int SatelliteSource::updateInterval
 
    This property holds the desired interval between updates in milliseconds.
*/
int QDeclarativeSatelliteSource::updateInterval() const
{
    return m_source ? m_source->updateInterval() : m_updateInterval;
}
 
/*!
    \qmlproperty enumeration SatelliteSource::sourceError
    \readonly
 
    This property holds the error which last occurred with the backend data
    provider.
 
    \value SatelliteSource.AccessError
        The connection setup to the satellite
        backend failed because the application lacked the required
        privileges.
    \value SatelliteSource.ClosedError
        The satellite backend closed the
        connection, which happens for example in case the user is switching
        location services to off.
    \value SatelliteSource.NoError
        No error has occurred.
    \value SatelliteSource.UnknownSourceError
        An unidentified error occurred.
    \value SatelliteSource.UpdateTimeoutError
        The satellite information could not be retrieved within the specified timeout.
*/
QDeclarativeSatelliteSource::SourceError QDeclarativeSatelliteSource::sourceError() const
{
    return m_error;
}
 
/*!
    \qmlproperty string SatelliteSource::name
 
    This property holds the unique internal name for the plugin currently
    providing satellite information.
 
    Setting the property causes the SatelliteSource to use a particular
    backend plugin. If the SatelliteSource is active at the time that the name
    property is changed, it will become inactive. If the specified backend
    cannot be loaded the satellite source will become invalid.
 
    Changing the name property may cause the \l updateInterval property
    to change as well.
*/
QString QDeclarativeSatelliteSource::name() const
{
    return m_source ? m_source->sourceName() : m_name;
}
 
/*!
    \qmlproperty list<PluginParameter> SatelliteSource::parameters
    \readonly
    \qmldefault
 
    This property holds the list of plugin parameters.
 
    \sa PluginParameter
*/
QQmlListProperty<QDeclarativePluginParameter> QDeclarativeSatelliteSource::parameters()
{
    return QQmlListProperty<QDeclarativePluginParameter>(this, nullptr,
                                                         parameter_append,
                                                         parameter_count,
                                                         parameter_at,
                                                         parameter_clear);
}
 
/*!
    \qmlproperty list<geoSatelliteInfo> SatelliteSource::satellitesInUse
    \readonly
 
    This property holds the list of satellites that are currently in use.
    These are the satellites that are used to get a "fix" - that
    is, those used to determine the current position.
*/
QList<QGeoSatelliteInfo> QDeclarativeSatelliteSource::satellitesInUse() const
{
    return m_satellitesInUse;
}
 
/*!
    \qmlproperty list<geoSatelliteInfo> SatelliteSource::satellitesInView
    \readonly
 
    This property holds the list of satellites that are currently in view.
*/
QList<QGeoSatelliteInfo> QDeclarativeSatelliteSource::satellitesInView() const
{
    return m_satellitesInView;
}
 
void QDeclarativeSatelliteSource::setUpdateInterval(int updateInterval)
{
    if (m_updateInterval == updateInterval)
        return;
 
    const auto oldInterval = m_updateInterval;
 
    if (m_source) {
        m_source->setUpdateInterval(updateInterval);
        // The above call can set some other interval, for example if desired
        // updateInterval is less than minimum supported update interval. So
        // we need to read the value back explicitly.
        m_updateInterval = m_source->updateInterval();
    } else {
        m_updateInterval = updateInterval;
    }
    if (oldInterval != m_updateInterval)
        emit updateIntervalChanged();
}
 
void QDeclarativeSatelliteSource::setActive(bool active)
{
    if (active == m_active)
        return;
 
    if (active)
        start();
    else
        stop();
}
 
void QDeclarativeSatelliteSource::setName(const QString &name)
{
    if ((m_name == name) || (name.isEmpty() && m_defaultSourceUsed))
        return;
 
    if (m_componentComplete && m_parametersInitialized) {
        createSource(name); // it will update name and emit, if needed
    } else {
        m_name = name;
        emit nameChanged();
    }
}
 
void QDeclarativeSatelliteSource::componentComplete()
{
    m_componentComplete = true;
    m_parametersInitialized = true;
    for (QDeclarativePluginParameter *p: std::as_const(m_parameters)) {
        if (!p->isInitialized()) {
            m_parametersInitialized = false;
            connect(p, &QDeclarativePluginParameter::initialized,
                    this, &QDeclarativeSatelliteSource::onParameterInitialized,
                    Qt::SingleShotConnection);
        }
    }
 
    if (m_parametersInitialized)
        createSource(m_name);
}
 
/*!
    \qmlmethod bool SatelliteSource::setBackendProperty(string name, var value)
 
    Sets the backend-specific property named \a name to \a value.
    Returns true on success, false otherwise, including if called on an
    uninitialized SatelliteSource.
*/
bool QDeclarativeSatelliteSource::setBackendProperty(const QString &name, const QVariant &value)
{
    if (m_source)
        return m_source->setBackendProperty(name, value);
    return false;
}
 
/*!
    \qmlmethod var SatelliteSource::backendProperty(string name)
 
    Returns the value of the backend-specific property named \a name, if
    present. Otherwise, including if called on an uninitialized SatelliteSource,
    the return value will be invalid.
*/
QVariant QDeclarativeSatelliteSource::backendProperty(const QString &name) const
{
    return m_source ? m_source->backendProperty(name) : QVariant{};
}
 
/*!
    \qmlmethod void SatelliteSource::update(int timeout = 0)
 
    A convenience method to request a single update from the satellite source.
    If there is no source available, this method has no effect.
 
    If the satellite source is not active, it will be activated for as
    long as it takes to receive an update, or until the request times
    out. The request timeout period is plugin-specific.
 
    The \a timeout is specified in milliseconds. If the \a timeout is zero
    (the default value), it defaults to a reasonable timeout period as
    appropriate for the source.
 
    \sa start(), stop(), active
*/
void QDeclarativeSatelliteSource::update(int timeout)
{
    if (m_componentComplete && m_parametersInitialized) {
        executeSingleUpdate(timeout);
    } else {
        m_singleUpdateDesiredTimeout = timeout;
        m_singleUpdateRequested = true;
    }
}
 
/*!
    \qmlmethod void SatelliteSource::start()
 
    Requests updates from the satellite source. Uses \l updateInterval if set,
    default interval otherwise. If there is no source available, this method
    has no effect.
 
    \sa stop(), update(), active
*/
void QDeclarativeSatelliteSource::start()
{
    if (m_componentComplete && m_parametersInitialized)
        executeStart();
    else
        m_startRequested = true;
}
 
/*!
    \qmlmethod void SatelliteSource::stop()
 
    Stops updates from the satellite source. If there is no source available or
    it is not active, this method has no effect.
 
    \sa start(), update(), active
*/
void QDeclarativeSatelliteSource::stop()
{
    if (m_source) {
        m_source->stopUpdates();
        m_regularUpdates = false;
 
        if (m_active && !m_singleUpdate) {
            m_active = false;
            emit activeChanged();
        }
    } else {
        m_startRequested = false;
    }
}
 
void QDeclarativeSatelliteSource::sourceErrorReceived(const QGeoSatelliteInfoSource::Error error)
{
    const auto oldError = m_error;
    m_error = static_cast<SourceError>(error);
    if (m_error != oldError)
        emit sourceErrorChanged();
 
    // if an error occurred during single update, the update is stopped, so we
    // need to change the active state.
    if (m_singleUpdate) {
        m_singleUpdate = false;
        if (m_active && !m_regularUpdates) {
            m_active = false;
            emit activeChanged();
        }
    }
}
 
void QDeclarativeSatelliteSource::onParameterInitialized()
{
    m_parametersInitialized = true;
    for (QDeclarativePluginParameter *p: std::as_const(m_parameters)) {
        if (!p->isInitialized()) {
            m_parametersInitialized = false;
            break;
        }
    }
 
    // m_componentComplete == true here
    if (m_parametersInitialized)
        createSource(m_name);
}
 
void QDeclarativeSatelliteSource::satellitesInViewUpdateReceived(const QList<QGeoSatelliteInfo> &satellites)
{
    m_satellitesInView = satellites;
    emit satellitesInViewChanged();
    handleSingleUpdateReceived();
}
 
void QDeclarativeSatelliteSource::satellitesInUseUpdateReceived(const QList<QGeoSatelliteInfo> &satellites)
{
    m_satellitesInUse = satellites;
    emit satellitesInUseChanged();
    handleSingleUpdateReceived();
}
 
QVariantMap QDeclarativeSatelliteSource::parameterMap() const
{
    QVariantMap map;
    for (const auto *parameter : std::as_const(m_parameters))
        map.insert(parameter->name(), parameter->value());
    return map;
}
 
void QDeclarativeSatelliteSource::createSource(const QString &newName)
{
    if (m_source && m_source->sourceName() == newName)
        return;
 
    const auto oldName = name();
    const bool oldIsValid = isValid();
    const bool oldActive = isActive();
    const auto oldUpdateInterval = updateInterval();
 
    if (m_source) {
        m_source->disconnect(this);
        m_source->stopUpdates();
        m_source.reset(nullptr);
        m_active = false;
    }
 
    if (!newName.isEmpty()) {
        m_source.reset(QGeoSatelliteInfoSource::createSource(newName, parameterMap(), nullptr));
        m_defaultSourceUsed = false;
    } else {
        m_source.reset(QGeoSatelliteInfoSource::createDefaultSource(parameterMap(), nullptr));
        m_defaultSourceUsed = true;
    }
 
    if (m_source) {
        connect(m_source.get(), &QGeoSatelliteInfoSource::errorOccurred,
                this, &QDeclarativeSatelliteSource::sourceErrorReceived);
        connect(m_source.get(), &QGeoSatelliteInfoSource::satellitesInViewUpdated,
                this, &QDeclarativeSatelliteSource::satellitesInViewUpdateReceived);
        connect(m_source.get(), &QGeoSatelliteInfoSource::satellitesInUseUpdated,
                this, &QDeclarativeSatelliteSource::satellitesInUseUpdateReceived);
 
        m_name = m_source->sourceName();
        m_source->setUpdateInterval(m_updateInterval);
        m_updateInterval = m_source->updateInterval();
    } else {
        m_name = newName;
        m_defaultSourceUsed = false;
    }
 
    if (oldName != name())
        emit nameChanged();
 
    if (oldIsValid != isValid())
        emit validityChanged();
 
    if (oldActive != isActive())
        emit activeChanged();
 
    if (oldUpdateInterval != updateInterval())
        emit updateIntervalChanged();
 
    if (m_startRequested) {
        m_startRequested = false;
        executeStart();
    }
    if (m_singleUpdateRequested) {
        m_singleUpdateRequested = false;
        executeSingleUpdate(m_singleUpdateDesiredTimeout);
    }
}
 
void QDeclarativeSatelliteSource::handleSingleUpdateReceived()
{
    if (m_singleUpdate) {
        m_singleUpdate = false;
        if (m_active && !m_regularUpdates) {
            m_active = false;
            emit activeChanged();
        }
    }
}
 
void QDeclarativeSatelliteSource::executeStart()
{
    if (m_source) {
        m_regularUpdates = true;
        if (!m_active) {
            m_active = true;
            emit activeChanged();
        }
        m_source->startUpdates();
    }
}
 
void QDeclarativeSatelliteSource::executeSingleUpdate(int timeout)
{
    if (m_source) {
        m_singleUpdate = true;
        if (!m_active) {
            m_active = true;
            emit activeChanged();
        }
        m_source->requestUpdate(timeout);
    }
}
 
void QDeclarativeSatelliteSource::parameter_append(PluginParameterProperty *prop,
                                                   QDeclarativePluginParameter *parameter)
{
    auto *src = static_cast<QDeclarativeSatelliteSource *>(prop->object);
    src->m_parameters.append(parameter);
}
 
qsizetype QDeclarativeSatelliteSource::parameter_count(PluginParameterProperty *prop)
{
    return static_cast<QDeclarativeSatelliteSource *>(prop->object)->m_parameters.size();
}
 
QDeclarativePluginParameter *
QDeclarativeSatelliteSource::parameter_at(PluginParameterProperty *prop, qsizetype index)
{
    return static_cast<QDeclarativeSatelliteSource *>(prop->object)->m_parameters[index];
}
 
void QDeclarativeSatelliteSource::parameter_clear(PluginParameterProperty *prop)
{
    auto *src = static_cast<QDeclarativeSatelliteSource *>(prop->object);
    src->m_parameters.clear();
}
 
QT_END_NAMESPACE