1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtPositioning module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include <QGeoAreaMonitorInfo>
41#include <QDateTime>
42#include <QSharedData>
43#include <QUuid>
44#include <QDataStream>
45
46#ifndef QT_NO_DEBUG_STREAM
47#include <QDebug>
48#endif
49
50QT_BEGIN_NAMESPACE
51
52/*!
53 \class QGeoAreaMonitorInfo
54 \inmodule QtPositioning
55 \since 5.2
56 \ingroup QtPositioning-positioning
57
58 \brief The QGeoAreaMonitorInfo class describes the parameters of an area or region
59 to be monitored for proximity.
60
61 The purpose of area monitoring is to inform a user when he/she comes close to an area of
62 interest. In general such an area is described by a \l QGeoCircle. The circle's center
63 represents the place of interest and the area around it identifies the geographical region
64 within which notifications are sent.
65
66 A QGeoAreaMonitorInfo object is valid if it has a non-empty name and a valid \l area().
67 Such objects must be registered with a \l QGeoAreaMonitorSource to start and stop the
68 monitoring process. Note that extensive monitoring can be very resource consuming
69 because the positioning engine must remain active and has to match the current position
70 with each QGeoAreaMonitorInfo instance.
71
72 To further reduce the burden on the system there are optional attributes which can
73 set. Each monitored area can have an expiry date which automatically removes the
74 to-be-monitored area from the monitoring source once the expiry date has been reached.
75 Another option is to adjust the persistence of a monitored area. A QGeoAreaMonitorInfo
76 that \l isPersistent() will remain active beyond
77 the current applications lifetime. If an area is entered while the monitoring
78 application is not running the application will be started. Note that this feature is
79 not available on all platforms. Its availability can be checked via
80 \l QGeoAreaMonitorSource::supportedAreaMonitorFeatures().
81
82 \sa QGeoAreaMonitorSource
83
84 */
85
86class QGeoAreaMonitorInfoPrivate : public QSharedData
87{
88public:
89 QGeoAreaMonitorInfoPrivate() : QSharedData(), persistent(false) {}
90 QGeoAreaMonitorInfoPrivate(const QGeoAreaMonitorInfoPrivate &other)
91 : QSharedData(other)
92 {
93 uid = other.uid;
94 name = other.name;
95 shape = other.shape;
96 persistent = other.persistent;
97 notificationParameters = other.notificationParameters;
98 expiry = other.expiry;
99 }
100 ~QGeoAreaMonitorInfoPrivate() {}
101
102 QUuid uid;
103 QString name;
104 QGeoShape shape;
105 bool persistent;
106 QVariantMap notificationParameters;
107 QDateTime expiry;
108};
109
110/*!
111 Constructs a QGeoAreaMonitorInfo object with the specified \a name.
112
113 \sa name()
114 */
115QGeoAreaMonitorInfo::QGeoAreaMonitorInfo(const QString &name)
116{
117 d = new QGeoAreaMonitorInfoPrivate;
118 d->name = name;
119 d->uid = QUuid::createUuid();
120}
121
122/*!
123 Constructs a QGeoAreaMonitorInfo object as a copy of \a other.
124 */
125QGeoAreaMonitorInfo::QGeoAreaMonitorInfo(const QGeoAreaMonitorInfo &other)
126 : d(other.d)
127{
128}
129
130/*!
131 Destructor
132 */
133QGeoAreaMonitorInfo::~QGeoAreaMonitorInfo()
134{
135}
136
137/*!
138 Assigns \a other to this QGeoAreaMonitorInfo object and returns a reference
139 to this QGeoAreaMonitorInfo object.
140 */
141QGeoAreaMonitorInfo &QGeoAreaMonitorInfo::operator=(const QGeoAreaMonitorInfo &other)
142{
143 d = other.d;
144 return *this;
145}
146
147/*!
148 Returns true if all of this object's values are the same as those of
149 \a other.
150*/
151bool QGeoAreaMonitorInfo::operator==(const QGeoAreaMonitorInfo &other) const
152{
153 return (d->name == other.d->name &&
154 d->uid == other.d->uid &&
155 d->shape == other.d->shape &&
156 d->persistent == other.d->persistent &&
157 d->expiry == other.d->expiry &&
158 d->notificationParameters == other.d->notificationParameters);
159}
160
161/*!
162 Returns true if any of this object's values are not the same as those of
163 \a other.
164*/
165bool QGeoAreaMonitorInfo::operator!=(const QGeoAreaMonitorInfo &other) const
166{
167 return !QGeoAreaMonitorInfo::operator ==(other);
168}
169
170/*!
171 Returns the name of the QGeoAreaMonitorInfo object. The name should be used to
172 for user-visibility purposes.
173 */
174QString QGeoAreaMonitorInfo::name() const
175{
176 return d->name;
177}
178
179/*!
180 Sets the user visibile \a name.
181 */
182void QGeoAreaMonitorInfo::setName(const QString &name)
183{
184 if (d->name != name)
185 d->name = name;
186}
187
188/*!
189 Returns the identifier of the QGeoAreaMonitorInfo object.
190 The identifier is automatically generated upon construction of a new
191 QGeoAreaMonitorInfo object.
192*/
193
194QString QGeoAreaMonitorInfo::identifier() const
195{
196 return d->uid.toString();
197}
198
199/*!
200 Returns true, if the monitor is valid. A valid QGeoAreaMonitorInfo has a non-empty name()
201 and the monitored area is not \l {QGeoShape::isEmpty()}{empty()}.
202 Otherwise this function returns false.
203 */
204bool QGeoAreaMonitorInfo::isValid() const
205{
206 return (!d->name.isEmpty() && !d->shape.isEmpty());
207}
208
209/*!
210 Returns the boundaries of the to-be-monitored area. This area must not be empty.
211
212 \sa setArea()
213 */
214QGeoShape QGeoAreaMonitorInfo::area() const
215{
216 return d->shape;
217}
218
219/*!
220 Sets the to-be-monitored area to \a newShape.
221
222 \sa area()
223 */
224void QGeoAreaMonitorInfo::setArea(const QGeoShape &newShape)
225{
226 d->shape = newShape;
227}
228
229/*!
230 Returns the expiry date.
231
232 After an active QGeoAreaMonitorInfo has expired the region is no longer monitored
233 and the QGeoAreaMonitorInfo object is removed from the list of
234 \l {QGeoAreaMonitorSource::activeMonitors()}{active monitors}.
235
236 If the expiry \l QDateTime is invalid the QGeoAreaMonitorInfo object is treated as not having
237 an expiry date. This implies an indefinite monitoring period if the object is persistent or
238 until the current application closes if the object is non-persistent.
239
240 \sa QGeoAreaMonitorSource::activeMonitors()
241 */
242QDateTime QGeoAreaMonitorInfo::expiration() const
243{
244 return d->expiry;
245}
246
247/*!
248 Sets the expiry date and time to \a expiry.
249 */
250void QGeoAreaMonitorInfo::setExpiration(const QDateTime &expiry)
251{
252 d->expiry = expiry;
253}
254
255/*!
256 Returns true if the QGeoAreaMonitorInfo is persistent.
257 The default value for this property is false.
258
259 A non-persistent QGeoAreaMonitorInfo will be removed by the system once
260 the application owning the monitor object stops. Persistent objects remain
261 active and can be retrieved once the application restarts.
262
263 If the system triggers an event associated to a persistent QGeoAreaMonitorInfo
264 the relevant application will be re-started and the appropriate signal emitted.
265
266 \sa setPersistent()
267 */
268bool QGeoAreaMonitorInfo::isPersistent() const
269{
270 return d->persistent;
271}
272
273/*!
274 Sets the QGeoAreaMonitorInfo objects persistence to \a isPersistent.
275
276 Note that setting this flag does not imply that QGeoAreaMonitorInfoSource supports persistent
277 monitoring. \l QGeoAreaMonitorSource::supportedAreaMonitorFeatures() can be used to
278 check for this feature's availability.
279
280 \sa isPersistent()
281 */
282void QGeoAreaMonitorInfo::setPersistent(bool isPersistent)
283{
284 d->persistent = isPersistent;
285}
286
287
288/*!
289 Returns the set of platform specific paraemters used by this QGeoAreaMonitorInfo.
290
291 \sa setNotificationParameters()
292 */
293QVariantMap QGeoAreaMonitorInfo::notificationParameters() const
294{
295 return d->notificationParameters;
296}
297
298/*!
299 Sets the set of platform specific \a parameters used by QGeoAreaMonitorInfo.
300
301 \sa notificationParameters()
302 */
303void QGeoAreaMonitorInfo::setNotificationParameters(const QVariantMap &parameters)
304{
305 d->notificationParameters = parameters;
306}
307
308#ifndef QT_NO_DATASTREAM
309
310/*!
311 \fn QDataStream &operator<<(QDataStream &stream, const QGeoAreaMonitorInfo &monitor)
312 \relates QGeoAreaMonitorInfo
313
314 Writes the given \a monitor to the specified \a stream.
315
316 \sa {Serializing Qt Data Types}
317*/
318QDataStream &operator<<(QDataStream &ds, const QGeoAreaMonitorInfo &monitor)
319{
320 ds << monitor.name() << monitor.d->uid << monitor.area()
321 << monitor.isPersistent() << monitor.notificationParameters() << monitor.expiration();
322 return ds;
323}
324
325/*!
326 \fn QDataStream &operator>>(QDataStream &stream, QGeoAreaMonitorInfo &monitor)
327 \relates QGeoAreaMonitorInfo
328
329 Reads a area monitoring data from the specified \a stream into the given
330 \a monitor.
331
332 \sa {Serializing Qt Data Types}
333*/
334
335QDataStream &operator>>(QDataStream &ds, QGeoAreaMonitorInfo &monitor)
336{
337 QString s;
338 ds >> s;
339 monitor = QGeoAreaMonitorInfo(s);
340
341 QUuid id;
342 ds >> id;
343 monitor.d->uid = id;
344
345 QGeoShape shape;
346 ds >> shape;
347 monitor.setArea(shape);
348
349 bool persistent;
350 ds >> persistent;
351 monitor.setPersistent(persistent);
352
353 QVariantMap map;
354 ds >> map;
355 monitor.setNotificationParameters(map);
356
357 QDateTime dt;
358 ds >> dt;
359 monitor.setExpiration(dt);
360
361 return ds;
362}
363
364#endif
365
366#ifndef QT_NO_DEBUG_STREAM
367QDebug operator<<(QDebug dbg, const QGeoAreaMonitorInfo &monitor)
368{
369 QDebugStateSaver saver(dbg);
370 dbg.nospace() << "QGeoAreaMonitorInfo(\"" << qPrintable(monitor.name())
371 << "\", " << monitor.area()
372 << ", persistent: " << monitor.isPersistent()
373 << ", expiry: " << monitor.expiration() << ")";
374 return dbg;
375}
376
377#endif
378
379QT_END_NAMESPACE
380

source code of qtlocation/src/positioning/qgeoareamonitorinfo.cpp