A GeotriggerMonitor monitors a Geotrigger condition and, when it is met, results in a GeotriggerNotificationInfo. More...
| Header: | #include <GeotriggerMonitor.h> |
| Since: | Esri::ArcGISRuntime 100.12 |
| Inherits: | Esri::ArcGISRuntime::Object |
Public Functions
| GeotriggerMonitor(Esri::ArcGISRuntime::Geotrigger *geotrigger, QObject *parent = nullptr) | |
| virtual | ~GeotriggerMonitor() override |
| Esri::ArcGISRuntime::Geotrigger * | geotrigger() const |
| QFuture<void> | startAsync() |
| Esri::ArcGISRuntime::GeotriggerMonitorStatus | status() const |
| void | stop() |
| Esri::ArcGISRuntime::Error | warning() const |
Signals
| void | geotriggerNotification(Esri::ArcGISRuntime::GeotriggerNotificationInfo *geotriggerNotificationInfo) |
| void | statusChanged(Esri::ArcGISRuntime::GeotriggerMonitorStatus status) |
| void | warningChanged(const Esri::ArcGISRuntime::Error &warning) |
Detailed Description
A Geotrigger defines a query that is evaluated against GIS data as it changes in real time. For example, "Notify me when my device location enters one of my target areas" or "Notify me when my device location is within 50 meters of my destination". The process of monitoring a Geotrigger is also known as "Geofencing".
A GeotriggerMonitor is created with a Geotrigger that it continually checks to determine whether the condition has been met.
Once a GeotriggerMonitor is created, you begin checking the condition by calling startAsync. Once you are finished, call stop. When a Geotrigger evaluates to true, a geotriggerNotification is sent. You can subscribe to the notification info to receive details of where the Geotrigger was activated and the condition that was met.
A GeotriggerMonitor can continue monitoring its Geotrigger condition when a mobile application is in the background. To enable this in an iOS or Android application, the following is recommended:
- Use a LocationGeotriggerFeed with a DefaultLocationDataSource based on the GPS of the device.
- Add manifest entries and request user permissions to allow background location updates.
The GeotriggerMonitor uses processing time provided by device location updates to monitor the active geotrigger. For backgrounded applications, the timing of location updates (and therefore the timing of geotrigger notifications) is determined by the operating system. If a FenceGeotrigger uses FeatureFenceParameters that reference a ServiceFeatureTable, and the table is associated with a FeatureLayer that has a non-zero FeatureLayer::refreshInterval, the geotrigger monitor requests fence updates from the server on that interval even when the application is in the background.
Relevant samples:
- Set up location-driven Geotriggers: Create a notification every time a given location data source has entered and/or exited a set of features or graphics.
Member Function Documentation
[explicit] GeotriggerMonitor::GeotriggerMonitor (Esri::ArcGISRuntime::Geotrigger *geotrigger, QObject *parent = nullptr)
Constructs a GeotriggerMonitor with a Geotrigger condition.
- geotrigger - The Geotrigger which will be monitored.
- parent - The optional parent QObject.
[override virtual] GeotriggerMonitor::~GeotriggerMonitor ()
Destructor.
Esri::ArcGISRuntime::Geotrigger *GeotriggerMonitor::geotrigger() const
Returns the Geotrigger that will be monitored.
[signal] void GeotriggerMonitor::geotriggerNotification (Esri::ArcGISRuntime::GeotriggerNotificationInfo *geotriggerNotificationInfo )
Indicates that the GeotriggerMonitor condition has been meet.
- geotriggerNotificationInfo - The GeotriggerNotificationInfo that is emitted.
To handle notifications, connect to this signal and inspect the geotriggerNotificationInfo.
The returned GeotriggerNotificationInfo object has the GeotriggerMonitor as its parent.
connect(m_monitor, &GeotriggerMonitor::geotriggerNotification, this, [this](GeotriggerNotificationInfo* notification) { // Ensure the notification object is cleaned up once it has been inspected. QScopedPointer<GeotriggerNotificationInfo> scopedGeotriggerNotification(notification); qDebug() << notification->message(); }
See also Returned QObjects Parenting.
[since Esri::ArcGISRuntime 200.2] QFuture<void> GeotriggerMonitor::startAsync ()
Starts evaluating the GeotriggerMonitor.
When the GeotriggerMonitor is successfully performing checks, the status will be GeotriggerMonitorStatus::Started.
This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.
See Working with QFuture for further details.
This function was introduced in Esri::ArcGISRuntime 200.2.
Esri::ArcGISRuntime::GeotriggerMonitorStatus GeotriggerMonitor::status() const
Returns the current monitoring status of the GeotriggerMonitor.
A GeotriggerMonitor begins with a monitoring status of GeotriggerMonitorStatus::Stopped and changes to GeotriggerMonitorStatus::Started when you call startAsync. When you call stop, the monitoring status changes to GeotriggerMonitorStatus::Stopped.
[signal] void GeotriggerMonitor::statusChanged (Esri::ArcGISRuntime::GeotriggerMonitorStatus status)
Indicates that the status property has changed.
- status - The GeotriggerMonitorStatus of the geotrigger monitor.
void GeotriggerMonitor::stop()
Returns stops evaluating the GeotriggerMonitor.
Stopping the GeotriggerMonitor prevents the condition from being evaluated and notifications from being sent. If you are using a LocationGeotriggerFeed created from a AbstractLocationDataSource, the data source must also be stopped to turn off GPS receivers etc.
When the GeotriggerMonitor is stopped, the status will be GeotriggerMonitorStatus::Stopped.
Esri::ArcGISRuntime::Error GeotriggerMonitor::warning() const
Returns an error that describes a problem encountered while monitoring the Geotrigger.
A warning can occur at various stages of monitoring a Geotrigger:
- when starting the GeotriggerMonitor
- when accessing the components of the Geotrigger such as the GeotriggerFeed
- when performing ongoing monitoring
If the problem is resolved, this property will be cleared.
Problems that occur when starting the GeotriggerMonitor result in a status of GeotriggerMonitorStatus::FailedToStart. These issues must be fixed and start called again before you will receive any notifications. For example, if the Geotrigger::messageExpression is an invalid ArcadeExpression, monitoring cannot be carried out.
Problems that occur when accessing the components of the Geotrigger will not prevent the GeotriggerMonitor from starting. However, until the problem is resolved, you will not receive any notifications. For example, if a LocationGeotriggerFeed uses a AbstractLocationDataSource that is not started, you will not receive any notifications. After the AbstractLocationDataSource is successfully started, monitoring will resume. If a FenceParameters has no valid data for a fence, you will not receive any notifications.
Problems that occur during ongoing monitoring relate to issues with individual objects, such as the graphics that make up the fences for a GraphicFenceParameters. These warnings do not prevent notifications from being sent for other valid fences. For example, a fence is considered invalid if it has:
- an empty Geometry
- a missing SpatialReference
- a point or polyline Geometry and a buffer distance of 0
- a point or polyline Geometry and a buffer distance of 0
[signal] void GeotriggerMonitor::warningChanged (const Esri::ArcGISRuntime::Error &warning)
Indicates that the warning property has changed.
- warning - The Error of the geotrigger monitor.