Revision control
Copy as Markdown
// Copyright (C) 2016 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 <QtCore/private/qobject_p.h>
#include <QGeoAreaMonitorSource>
#include "qgeopositioninfosourcefactory.h"
#include "qgeopositioninfosource_p.h"
/*!
\class QGeoAreaMonitorSource
\inmodule QtPositioning
\ingroup QtPositioning-positioning
\since 5.2
\brief The QGeoAreaMonitorSource class enables the detection of proximity
changes for a specified set of coordinates.
A QGeoAreaMonitorSource emits signals when the current position is in
range, or has moved out of range, of a specified area.
Each area is specified by a \l QGeoAreaMonitorInfo object.
For example:
\snippet cpp/cppqml.cpp BigBen
\c QGeoAreaMonitorSource follows a singleton pattern. Each instance of
the class with the same \l sourceName() shares the same area monitoring backend.
If a new \l QGeoAreaMonitorInfo object is added via \l startMonitoring()
or \l requestUpdate() it can be retrieved by another instance of this class
(provided that they are sourced from the same area monitor provider plug-in).
The same singleton pattern applies to the \l QGeoPositionInfoSource instance
used by this class. The following code snippet emphasizes the behavior:
\code
QGeoAreaMonitorSource *s1 = QGeoAreaMonitorSource::createSource("blah", this);
QGeoAreaMonitorSource *s2 = QGeoAreaMonitorSource::createSource("blah", this);
QVERIFY(s1->positionInfoSource() == s2->positionInfoSource);
\endcode
*/
QT_BEGIN_NAMESPACE
class QGeoAreaMonitorSourcePrivate : public QObjectPrivate
{
public:
QGeoPositionInfoSource *source;
QString providerName;
};
/*!
\enum QGeoAreaMonitorSource::Error
Defines the types of positioning methods.
The Error enumeration represents the errors which can occur.
\value AccessError The connection setup to the remote area monitoring backend failed because the
application lacked the required privileges.
\value InsufficientPositionInfo The area monitoring source could not retrieve a location fix or
the accuracy of the fix is not high enough to provide an effective area monitoring.
\value NoError No error has occurred.
\value UnknownSourceError An unidentified error occurred.
*/
/*!
\enum QGeoAreaMonitorSource::AreaMonitorFeature
Defines the types of area monitoring capabilities.
\value PersistentAreaMonitorFeature QGeoAreaMonitorInfo instances can be made persistent.
A persistent monitor continues to be active even when the application managing the monitor is
not running.
\value AnyAreaMonitorFeature Matches all possible area monitoring features.
*/
/*!
\fn virtual AreaMonitoringFeatures QGeoAreaMonitorSource::supportedAreaMonitorFeatures() const = 0;
Returns the area monitoring features available to this source.
*/
/*!
\fn virtual QGeoAreaMonitorSource::Error QGeoAreaMonitorSource::error() const
Returns the type of error that last occurred.
\note Since Qt6 the last error is always reset when calling
startMonitoring() or requestUpdate().
*/
/*!
Creates a monitor source with the given \a parent.
*/
QGeoAreaMonitorSource::QGeoAreaMonitorSource(QObject *parent)
: QObject(*new QGeoAreaMonitorSourcePrivate, parent)
{
Q_D(QGeoAreaMonitorSource);
d->source = nullptr;
}
/*!
Destroys the monitor source.
*/
QGeoAreaMonitorSource::~QGeoAreaMonitorSource()
{
}
/*!
Creates and returns a monitor source with the given \a parent that
monitors areas using resources on the underlying system.
Returns \c nullptr if the system has no support for position monitoring.
*/
QGeoAreaMonitorSource *QGeoAreaMonitorSource::createDefaultSource(QObject *parent)
{
const QList<QCborMap> plugins = QGeoPositionInfoSourcePrivate::pluginsSorted();
for (const QCborMap &obj : plugins) {
if (obj.value(QStringLiteral("Monitor")).isBool()
&& obj.value(QStringLiteral("Monitor")).toBool())
{
QGeoAreaMonitorSource *s = nullptr;
auto factory = QGeoPositionInfoSourcePrivate::loadFactory(obj);
if (factory)
s = factory->areaMonitor(parent, QVariantMap());
if (s)
s->d_func()->providerName = obj.value(QStringLiteral("Provider")).toString();
return s;
}
}
return nullptr;
}
/*!
Creates and returns a monitor source with the given \a parent,
by loading the plugin named \a sourceName.
Returns \c nullptr if the plugin cannot be found.
*/
QGeoAreaMonitorSource *QGeoAreaMonitorSource::createSource(const QString &sourceName, QObject *parent)
{
auto plugins = QGeoPositionInfoSourcePrivate::plugins();
if (plugins.contains(sourceName)) {
const auto metaData = plugins.value(sourceName);
QGeoAreaMonitorSource *s = nullptr;
auto factory = QGeoPositionInfoSourcePrivate::loadFactory(metaData);
if (factory)
s = factory->areaMonitor(parent, QVariantMap());
if (s)
s->d_func()->providerName = metaData.value(QStringLiteral("Provider")).toString();
return s;
}
return nullptr;
}
/*!
Returns a list of available monitor plugins, including the default system
backend if one is available.
*/
QStringList QGeoAreaMonitorSource::availableSources()
{
QStringList plugins;
const auto meta = QGeoPositionInfoSourcePrivate::plugins();
for (auto it = meta.cbegin(), end = meta.cend(); it != end; ++it) {
if (it.value().value(QStringLiteral("Monitor")).isBool()
&& it.value().value(QStringLiteral("Monitor")).toBool()) {
plugins << it.key();
}
}
return plugins;
}
/*!
Returns the unique name of the area monitor source implementation in use.
This is the same name that can be passed to createSource() in order to
create a new instance of a particular area monitor source implementation.
*/
QString QGeoAreaMonitorSource::sourceName() const
{
Q_D(const QGeoAreaMonitorSource);
return d->providerName;
}
/*!
\since 6.2
Sets the backend-specific property named \a name to \a value.
Returns \c true on success, otherwise returns \c false.
Backend-specific properties can be used to configure the area monitoring
subsystem behavior at runtime.
\sa backendProperty()
*/
bool QGeoAreaMonitorSource::setBackendProperty(const QString &name, const QVariant &value)
{
Q_UNUSED(name);
Q_UNUSED(value);
return false;
}
/*!
\since 6.2
Returns the value of the backend-specific property named \a name,
if present. Otherwise the returned value will be invalid.
\sa setBackendProperty()
*/
QVariant QGeoAreaMonitorSource::backendProperty(const QString &name) const
{
Q_UNUSED(name);
return QVariant();
}
/*!
Returns the current QGeoPositionInfoSource used by this QGeoAreaMonitorSource
object. The function will return \l QGeoPositionInfoSource::createDefaultSource()
if no other object has been set.
The function returns \c nullptr if not even a default QGeoPositionInfoSource
exists.
Any usage of the returned \l QGeoPositionInfoSource instance should account
for the fact that it may reside in a different thread.
\sa QGeoPositionInfoSource, setPositionInfoSource()
*/
QGeoPositionInfoSource* QGeoAreaMonitorSource::positionInfoSource() const
{
Q_D(const QGeoAreaMonitorSource);
return d->source;
}
/*!
Sets the new \l QGeoPositionInfoSource to be used by this QGeoAreaMonitorSource object.
The area monitoring backend becomes the new QObject parent for \a newSource.
The previous \l QGeoPositionInfoSource object will be deleted. All QGeoAreaMonitorSource
instances based on the same \l sourceName() share the same QGeoPositionInfoSource
instance.
This may be useful when it is desirable to manipulate the positioning system
used by the area monitoring engine.
Note that ownership must be taken care of by subclasses of QGeoAreaMonitorSource.
Due to the singleton pattern behind this class \a newSource may be moved to a
new thread.
\sa positionInfoSource()
*/
void QGeoAreaMonitorSource::setPositionInfoSource(QGeoPositionInfoSource *newSource)
{
Q_D(QGeoAreaMonitorSource);
d->source = newSource;
}
/*!
\fn virtual bool QGeoAreaMonitorSource::startMonitoring(const QGeoAreaMonitorInfo &monitor)
Returns \c true if the monitoring of \a monitor could be successfully started; otherwise
returns \c false. A reason for not being able to start monitoring could be the unavailability
of an appropriate default position info source while no alternative QGeoPositionInfoSource
has been set via \l setPositionInfoSource().
If \a monitor is already active, the existing monitor object will be replaced by the new \a monitor reference.
The identification of QGeoAreaMonitorInfo instances happens via \l QGeoAreaMonitorInfo::identifier().
Therefore this function can also be used to update active monitors.
If \a monitor has an expiry date that has been passed this function returns false. Calling
this function for an already via \l requestUpdate() registered single shot monitor
switches the monitor to a permanent monitoring mode.
Requesting persistent monitoring on a QGeoAreaMonitorSource instance fails if the area monitoring
backend doesn't support \l QGeoAreaMonitorSource::PersistentAreaMonitorFeature.
\note Since Qt6 this method always resets the last error to
\l {QGeoAreaMonitorSource::}{NoError} before starting monitoring.
\sa stopMonitoring()
*/
/*!
\fn virtual bool QGeoAreaMonitorSource::requestUpdate(const QGeoAreaMonitorInfo &monitor, const char *signal)
Enables single shot area monitoring. Area monitoring for \a monitor will be performed
until this QGeoAreaMonitorSource instance emits \a signal for the first time. Once
the signal was emitted, \a monitor is automatically removed from the list of
\l activeMonitors(). If \a monitor is invalid or has an expiry date that has
been passed, this function returns \c false.
\code
QGeoAreaMonitor singleShotMonitor;
QGeoAreaMonitorSource * source = QGeoAreaMonitorSource::createDefaultSource(this);
//...
bool ret = source->requestUpdate(singleShotMonitor,
SIGNAL(areaExited(QGeoAreaMonitor,QGeoPositionInfo)));
\endcode
The above \c singleShotMonitor object will cease to send updates once the \l areaExited() signal
was emitted for the first time. Until this point in time any other signal may be emitted
zero or more times depending on the area context.
It is not possible to simultanously request updates for more than one signal of the same monitor object.
The last call to this function determines the signal upon which the updates cease to continue.
At this stage only the \l areaEntered() and \l areaExited() signals can be used to
terminate the monitoring process.
Requesting persistent monitoring on a QGeoAreaMonitorSource instance fails if the area monitoring
backend doesn't support \l QGeoAreaMonitorSource::PersistentAreaMonitorFeature.
If \a monitor was already registered via \l startMonitoring() it is converted to a single
shot behavior.
\note Since Qt6 this method always resets the last error to
\l {QGeoAreaMonitorSource::}{NoError} before starting monitoring.
\sa startMonitoring(), stopMonitoring()
*/
/*!
\fn virtual bool QGeoAreaMonitorSource::stopMonitoring(const QGeoAreaMonitorInfo &monitor)
Returns true if \a monitor was successfully removed from the list of \l activeMonitors();
otherwise returns false. This behavior is independent on whether \a monitor was registered
via \l startMonitoring() or \l requestUpdate().
*/
/*!
\fn virtual QList<QGeoAreaMonitorInfo> QGeoAreaMonitorSource::activeMonitors() const
Returns the list of all active monitors known to the QGeoAreaMonitorSource object.
An active monitor was started via startMonitoring(). For every active
monitor the source object will emit the required signals, such as
areaEntered() or areaExited(). Multiple \l QGeoAreaMonitorSource instances
within the same application share the same active monitor objects.
Unless an active QGeoAreaMonitorInfo \l {QGeoAreaMonitorInfo::isPersistent()}{isPersistent()} an active QGeoAreaMonitorInfo
will be stopped once the current application terminates.
*/
/*!
\fn virtual QList<QGeoAreaMonitorInfo> QGeoAreaMonitorSource::activeMonitors(const QGeoShape &lookupArea) const
Returns the list of all active monitors known to the QGeoAreaMonitorSource object whose
center lies within \a lookupArea. If \a lookupArea is empty the returned list will be empty.
An active monitor was started via startMonitoring(). For every active
monitor the source object will emit the required signals, such as
areaEntered() or areaExited(). Multiple \l QGeoAreaMonitorSource instances
within the same application share the same active monitor objects.
Unless an active QGeoAreaMonitorInfo \l {QGeoAreaMonitorInfo::isPersistent()}{isPersistent()} an active QGeoAreaMonitorInfo
will be stopped once the current application terminates.
\sa QGeoShape
*/
/*!
\fn void QGeoAreaMonitorSource::monitorExpired(const QGeoAreaMonitorInfo &monitor)
Emitted when \a monitor has expired. An expired area monitor is automatically
removed from the list of \l activeMonitors().
\sa activeMonitors()
*/
/*!
\fn void QGeoAreaMonitorSource::areaEntered(const QGeoAreaMonitorInfo &monitor, const QGeoPositionInfo &update)
Emitted when the current position has moved from a position outside of the active \a monitor
to a position within the monitored area.
The \a update holds the new position.
*/
/*!
\fn void QGeoAreaMonitorSource::areaExited(const QGeoAreaMonitorInfo &monitor, const QGeoPositionInfo &update)
Emitted when the current position has moved from a position within the active \a monitor
to a position outside the monitored area.
The \a update holds the new position.
*/
/*!
\fn void QGeoAreaMonitorSource::errorOccurred(QGeoAreaMonitorSource::Error areaMonitoringError)
This signal is emitted after an error occurred. The \a areaMonitoringError
parameter describes the type of error that occurred.
*/
QT_END_NAMESPACE
#include "moc_qgeoareamonitorsource.cpp"