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 QtBluetooth 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 "qlowenergyconnectionparameters.h"
41
42QT_BEGIN_NAMESPACE
43
44class QLowEnergyConnectionParametersPrivate : public QSharedData
45{
46public:
47 QLowEnergyConnectionParametersPrivate()
48 : minInterval(7.5)
49 , maxInterval(4000)
50 , latency(0)
51 , timeout(32000)
52 {
53 }
54
55 double minInterval;
56 double maxInterval;
57 int latency;
58 int timeout;
59};
60
61/*!
62 \since 5.7
63 \class QLowEnergyConnectionParameters
64 \brief The QLowEnergyConnectionParameters class is used when requesting or reporting
65 an update of the parameters of a Bluetooth LE connection.
66
67 The connection parameters influence how often a master and a slave device synchronize
68 with each other. In general, a lower connection interval and latency means faster communication,
69 but also higher power consumption. How these criteria should be weighed against each other
70 is highly dependent on the concrete use case.
71
72 Android only indirectly permits the adjustment of this parameter set.
73 The platform separates the connection parameters into three categories (hight, low & balanced
74 priority). Each category implies a predefined set of values for \l minimumInterval(),
75 \l maximumInterval() and \l latency(). Additionally, the value ranges of each category can vary
76 from one Android device to the next. Qt uses the \l minimumInterval() to determine the target
77 category as follows:
78
79 \table
80 \header
81 \li minimumInterval()
82 \li Android priority
83 \row
84 \li interval < 30
85 \li CONNECTION_PRIORITY_HIGH
86 \row
87 \li 30 <= interval <= 100
88 \li CONNECTION_PRIORITY_BALANCED
89 \row
90 \li interval > 100
91 \li CONNECTION_PRIORITY_LOW_POWER
92 \endtable
93
94 The \l supervisionTimeout() cannot be changed on Android and is therefore ignored.
95
96
97 \inmodule QtBluetooth
98 \ingroup shared
99
100 \sa QLowEnergyController::requestConnectionUpdate
101 \sa QLowEnergyController::connectionUpdated
102*/
103
104
105/*!
106 Constructs a new object of this class. All values are initialized to valid defaults.
107 */
108QLowEnergyConnectionParameters::QLowEnergyConnectionParameters()
109 : d(new QLowEnergyConnectionParametersPrivate)
110{
111}
112
113/*! Constructs a new object of this class that is a copy of \a other. */
114QLowEnergyConnectionParameters::QLowEnergyConnectionParameters(const QLowEnergyConnectionParameters &other)
115 : d(other.d)
116{
117}
118
119/*! Destroys this object. */
120QLowEnergyConnectionParameters::~QLowEnergyConnectionParameters()
121{
122}
123
124/*! Makes this object a copy of \a other and returns the new value of this object. */
125QLowEnergyConnectionParameters &QLowEnergyConnectionParameters::operator=(const QLowEnergyConnectionParameters &other)
126{
127 d = other.d;
128 return *this;
129}
130
131/*!
132 Sets the range in which the connection interval should be. The actual value will be decided by
133 the controller. Both \a minimum and \a maximum are given in milliseconds.
134 If \a maximum is smaller than \a minimum, it will be set to the value of \a minimum.
135 The smallest possible connection interval is 7.5 milliseconds, the largest one is
136 4000 milliseconds.
137 \sa minimumInterval(), maximumInterval()
138 */
139void QLowEnergyConnectionParameters::setIntervalRange(double minimum, double maximum)
140{
141 d->minInterval = minimum;
142 d->maxInterval = qMax(minimum, maximum);
143}
144
145/*!
146 Returns the minimum connection interval in milliseconds. The default is 7.5.
147 \note If this object was emitted via \l QLowEnergyController::connectionUpdated(), then
148 this value is the same as \l maximumInterval() and refers to the actual
149 connection interval.
150 \sa setIntervalRange()
151 */
152double QLowEnergyConnectionParameters::minimumInterval() const
153{
154 return d->minInterval;
155}
156
157/*!
158 Returns the maximum connection interval in milliseconds. The default is 4000.
159 \note If this object was emitted via \l QLowEnergyController::connectionUpdated(), then
160 this value is the same as \l minimumInterval() and refers to the actual
161 connection interval.
162 \sa setIntervalRange()
163 */
164double QLowEnergyConnectionParameters::maximumInterval() const
165{
166 return d->maxInterval;
167}
168
169/*!
170 Sets the slave latency of the connection (that is, the number of connection events that a slave
171 device is allowed to ignore) to \a latency. The minimum value is 0, the maximum is 499.
172 \sa latency()
173 */
174void QLowEnergyConnectionParameters::setLatency(int latency)
175{
176 d->latency = latency;
177}
178
179/*!
180 Returns the slave latency of the connection.
181 \sa setLatency()
182*/
183int QLowEnergyConnectionParameters::latency() const
184{
185 return d->latency;
186}
187
188/*!
189 Sets the link supervision timeout to \a timeout milliseconds.
190 There are several constraints on this value: It must be in the range [100,32000] and it must be
191 larger than (1 + \l latency()) * 2 * \l maximumInterval().
192
193 On Android, this timeout is not adjustable and therefore ignored.
194
195 \sa supervisionTimeout()
196 */
197void QLowEnergyConnectionParameters::setSupervisionTimeout(int timeout)
198{
199 d->timeout = timeout;
200}
201
202/*!
203 Returns the link supervision timeout of the connection in milliseconds.
204 \sa setSupervisionTimeout()
205*/
206int QLowEnergyConnectionParameters::supervisionTimeout() const
207{
208 return d->timeout;
209}
210
211/*!
212 \fn void QLowEnergyConnectionParameters::swap(QLowEnergyConnectionParameters &other)
213 Swaps this object with \a other.
214 */
215
216/*!
217 Returns \a true if \a p1 and \a p2 are equal with respect to their public state,
218 otherwise returns false.
219 */
220bool operator==(const QLowEnergyConnectionParameters &p1, const QLowEnergyConnectionParameters &p2)
221{
222 if (p1.d == p2.d)
223 return true;
224 return p1.minimumInterval() == p2.minimumInterval()
225 && p1.maximumInterval() == p2.maximumInterval()
226 && p1.latency() == p2.latency()
227 && p1.supervisionTimeout() == p2.supervisionTimeout();
228}
229
230/*!
231 \fn bool operator!=(const QLowEnergyConnectionParameters &p1,
232 const QLowEnergyConnectionParameters &p2)
233 Returns \a true if \a p1 and \a p2 are not equal with respect to their public state,
234 otherwise returns false.
235 */
236
237QT_END_NAMESPACE
238