Revision control
Copy as Markdown
// 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