1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qlowenergyadvertisingdata.h"
5
6#include <cstring>
7
8QT_BEGIN_NAMESPACE
9
10class QLowEnergyAdvertisingDataPrivate : public QSharedData
11{
12public:
13 QLowEnergyAdvertisingDataPrivate()
14 : manufacturerId(QLowEnergyAdvertisingData::invalidManufacturerId())
15 , discoverability(QLowEnergyAdvertisingData::DiscoverabilityNone)
16 , includePowerLevel(false)
17 {
18 }
19
20 QString localName;
21 QByteArray manufacturerData;
22 QByteArray rawData;
23 QList<QBluetoothUuid> services;
24 quint16 manufacturerId;
25 QLowEnergyAdvertisingData::Discoverability discoverability;
26 bool includePowerLevel;
27};
28
29/*!
30 \since 5.7
31 \class QLowEnergyAdvertisingData
32 \brief The QLowEnergyAdvertisingData class represents the data to be broadcast during
33 Bluetooth Low Energy advertising.
34 \inmodule QtBluetooth
35 \ingroup shared
36
37 This data can include the device name, GATT services offered by the device, and so on.
38 The data set via this class will be used when advertising is started by calling
39 \l QLowEnergyController::startAdvertising(). Objects of this class can represent an
40 Advertising Data packet or a Scan Response packet.
41
42 \section2 Advertising Data Limitations
43
44 The maximum length of the advertisement data depends on the bluetooth
45 device and the platform bluetooth stack. For maximum compatibility, it is
46 recommended to limit the advertising data size to the legacy advertising
47 limit of 31 bytes.
48
49 If the variable-length data set via this class exceeds the supported limit,
50 the behavior will depend on the underlying Bluetooth stack implementation.
51 The most typical possibilities are:
52
53 \list
54 \li the extra data can be truncated or entirely left out;
55 \li the advertising fails to start.
56 \endlist
57
58 For example, on Android, advertising will fail if the advertising data is
59 larger than 31 bytes. On BlueZ DBus backend, the advertising length limit
60 and the behavior when it is exceeded is up to BlueZ; it may, for example
61 support extended advertising, or may fail to start the advertising.
62
63 \sa QLowEnergyAdvertisingParameters
64 \sa QLowEnergyController::startAdvertising()
65*/
66
67/*!
68 \enum QLowEnergyAdvertisingData::Discoverability
69
70 The discoverability of the advertising device as defined by the Generic Access Profile.
71
72 \value DiscoverabilityNone
73 The advertising device does not wish to be discoverable by scanning devices.
74 \value DiscoverabilityLimited
75 The advertising device wishes to be discoverable with a high priority. Note that this mode
76 is not compatible with using a white list. The value of
77 \l QLowEnergyAdvertisingParameters::filterPolicy() is always assumed to be
78 \l QLowEnergyAdvertisingParameters::IgnoreWhiteList when limited discoverability
79 is used.
80 \value DiscoverabilityGeneral
81 The advertising device wishes to be discoverable by scanning devices.
82 */
83
84/*!
85 Creates a new object of this class. All values are initialized to their defaults
86 according to the Bluetooth Low Energy specification.
87 */
88QLowEnergyAdvertisingData::QLowEnergyAdvertisingData() : d(new QLowEnergyAdvertisingDataPrivate)
89{
90}
91
92/*! Constructs a new object of this class that is a copy of \a other. */
93QLowEnergyAdvertisingData::QLowEnergyAdvertisingData(const QLowEnergyAdvertisingData &other)
94 : d(other.d)
95{
96}
97
98/*! Destroys this object. */
99QLowEnergyAdvertisingData::~QLowEnergyAdvertisingData()
100{
101}
102
103/*! Makes this object a copy of \a other and returns the new value of this object. */
104QLowEnergyAdvertisingData &QLowEnergyAdvertisingData::operator=(const QLowEnergyAdvertisingData &other)
105{
106 d = other.d;
107 return *this;
108}
109
110/*!
111 Specifies that \a name should be broadcast as the name of the device. If the full name does not
112 fit into the advertising data packet, an abbreviated name is sent, as described by the
113 Bluetooth Low Energy specification.
114
115 On Android, the local name cannot be changed. Android always uses the device name.
116 If this local name is not empty, the Android implementation includes the device name
117 in the advertisement packet; otherwise the device name is omitted from the advertisement
118 packet.
119
120 \sa localName()
121 */
122void QLowEnergyAdvertisingData::setLocalName(const QString &name)
123{
124 d->localName = name;
125}
126
127/*!
128 Returns the name of the local device that is to be advertised.
129
130 \sa setLocalName()
131 */
132QString QLowEnergyAdvertisingData::localName() const
133{
134 return d->localName;
135}
136
137/*!
138 Sets the manufacturer id and data. The \a id parameter is a company identifier as assigned
139 by the Bluetooth SIG. The \a data parameter is an arbitrary value.
140
141 \note \macos and iOS do not support advertising of manufacturer id or data,
142 so the provided parameters will be ignored on these platforms.
143 */
144void QLowEnergyAdvertisingData::setManufacturerData(quint16 id, const QByteArray &data)
145{
146 d->manufacturerId = id;
147 d->manufacturerData = data;
148}
149
150/*!
151 Returns the manufacturer id.
152 The default is \l QLowEnergyAdvertisingData::invalidManufacturerId(), which means
153 the data will not be advertised.
154 */
155quint16 QLowEnergyAdvertisingData::manufacturerId() const
156{
157 return d->manufacturerId;
158}
159
160/*!
161 Returns the manufacturer data. The default is an empty byte array.
162 */
163QByteArray QLowEnergyAdvertisingData::manufacturerData() const
164{
165 return d->manufacturerData;
166}
167
168/*!
169 Specifies whether to include the device's transmit power level in the advertising data. If
170 \a doInclude is \c true, the data will be included, otherwise it will not.
171 */
172void QLowEnergyAdvertisingData::setIncludePowerLevel(bool doInclude)
173{
174 d->includePowerLevel = doInclude;
175}
176
177/*!
178 Returns whether to include the device's transmit power level in the advertising data.
179 The default is \c false.
180 */
181bool QLowEnergyAdvertisingData::includePowerLevel() const
182{
183 return d->includePowerLevel;
184}
185
186/*!
187 Sets the discoverability type of the advertising device to \a mode.
188 \note Discoverability information can only appear in an actual advertising data packet. If
189 this object acts as scan response data, a call to this function will have no effect
190 on the scan response sent.
191 */
192void QLowEnergyAdvertisingData::setDiscoverability(QLowEnergyAdvertisingData::Discoverability mode)
193{
194 d->discoverability = mode;
195}
196
197/*!
198 Returns the discoverability mode of the advertising device.
199 The default is \l DiscoverabilityNone.
200 */
201QLowEnergyAdvertisingData::Discoverability QLowEnergyAdvertisingData::discoverability() const
202{
203 return d->discoverability;
204}
205
206/*!
207 Specifies that the service UUIDs in \a services should be advertised.
208 If the entire list does not fit into the packet, an incomplete list is sent as specified
209 by the Bluetooth Low Energy specification.
210 */
211void QLowEnergyAdvertisingData::setServices(const QList<QBluetoothUuid> &services)
212{
213 d->services = services;
214}
215
216/*!
217 Returns the list of service UUIDs to be advertised.
218 By default, this list is empty.
219 */
220QList<QBluetoothUuid> QLowEnergyAdvertisingData::services() const
221{
222 return d->services;
223}
224
225/*!
226 Sets the data to be advertised to \a data. If the value is not an empty byte array, it will
227 be sent as-is as the advertising data and all other data in this object will be ignored.
228 This can be used to send non-standard data.
229 \note If \a data is longer than 31 bytes, it will be truncated. It is the caller's responsibility
230 to ensure that \a data is well-formed.
231
232 Setting raw advertising data is only supported on the \l {Linux Specific}
233 {Linux Bluetooth Kernel API} backend. Other backends do not allow to specify
234 the raw advertising data as a global field.
235 */
236void QLowEnergyAdvertisingData::setRawData(const QByteArray &data)
237{
238 d->rawData = data;
239}
240
241/*!
242 Returns the user-supplied raw data to be advertised. The default is an empty byte array.
243 */
244QByteArray QLowEnergyAdvertisingData::rawData() const
245{
246 return d->rawData;
247}
248
249/*!
250 \fn void QLowEnergyAdvertisingData::swap(QLowEnergyAdvertisingData &other)
251 Swaps this object with \a other.
252 */
253
254/*!
255 \brief Returns \c true if \a a and \a b are equal with respect to their public state,
256 otherwise returns \c false.
257 \internal
258 */
259bool QLowEnergyAdvertisingData::equals(const QLowEnergyAdvertisingData &a,
260 const QLowEnergyAdvertisingData &b)
261{
262 if (a.d == b.d)
263 return true;
264 return a.discoverability() == b.discoverability()
265 && a.includePowerLevel() == b.includePowerLevel() && a.localName() == b.localName()
266 && a.manufacturerData() == b.manufacturerData()
267 && a.manufacturerId() == b.manufacturerId() && a.services() == b.services()
268 && a.rawData() == b.rawData();
269}
270
271/*!
272 \fn bool QLowEnergyAdvertisingData::operator!=(const QLowEnergyAdvertisingData &data1,
273 const QLowEnergyAdvertisingData &data2)
274 \brief Returns \c true if \a data1 and \a data2 are not equal with respect to their
275 public state, otherwise returns \c false.
276 */
277
278/*!
279 \fn bool QLowEnergyAdvertisingData::operator==(const QLowEnergyAdvertisingData &data1,
280 const QLowEnergyAdvertisingData &data2)
281 \brief Returns \c true if \a data1 and \a data2 are equal with respect to their public
282 state, otherwise returns \c false.
283 */
284
285/*!
286 \fn static quint16 QLowEnergyAdvertisingData::invalidManufacturerId();
287 Returns an invalid manufacturer id. If this value is set as the manufacturer id
288 (which it is by default), no manufacturer data will be present in the advertising data.
289 */
290
291QT_END_NAMESPACE
292

source code of qtconnectivity/src/bluetooth/qlowenergyadvertisingdata.cpp