Mistake on this page?
Report an issue in GitHub or email us
AdvertisingDataSimpleBuilder.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2020 ARM Limited
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
20 #define BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
21 
22 #include "platform/Span.h"
23 
24 #include "ble/common/UUID.h"
25 #include "ble/gap/AdvertisingDataBuilder.h"
26 
27 namespace ble {
28 
29 /**
30  * @addtogroup ble
31  * @{
32  * @addtogroup gap
33  * @{
34  */
35 
36 /**
37  * Build advertising data.
38  *
39  * It is a simplified version of AdvertisingDataBuilder that can generate
40  * advertising data "inline".
41  *
42  * It differs from AdvertisingDataBuilder on the following points:
43  * - The buffer used to build the advertising data is embedded in the object.
44  * - If insertion fails, an assertion is raised. Outside of debug mode, if an
45  * insertion fails, the buffer is not modified.
46  * - The API is fluent.
47  * - It hides advanced functions.
48  *
49  * @code
50  void setupAdvertisingData(ble::Gap& gap)
51  {
52  using namespace ble;
53  gap.setAdvertisingPayload(
54  LEGACY_ADVERTISING_HANDLE,
55  AdvertisingDataSimpleBuilder<LEGACY_ADVERTISING_MAX_SIZE>()
56  .setFlags()
57  .setName("My device", true)
58  .setAppearance(adv_data_appearance_t::GENERIC_HEART_RATE_SENSOR)
59  .setLocalService(ATT_UUID_HEART_RATE_SERVICE)
60  .getAdvertisingData()
61  );
62  }
63  * @endcode
64  */
65 template<size_t DataSize>
67 public:
68  /**
69  * Construct a AdvertisingDataSimpleBuilder
70  */
71  AdvertisingDataSimpleBuilder() : _buffer(), _builder(_buffer)
72  {
73  }
74 
75  /**
76  * Add device appearance in the advertising payload.
77  *
78  * @param[in] appearance The appearance to advertise.
79  *
80  * @return A reference to this object.
81  *
82  * @note If the field is already present in the payload, it is replaced.
83  */
85  {
86  ble_error_t res = _builder.setAppearance(appearance);
88  return *this;
89  }
90 
91  /**
92  * Add BLE flags in the advertising payload.
93  *
94  * @param[in] flags Bitfield describing the capability of the device. See
95  * allowed flags in Flags_t.
96  *
97  * @return A reference to this object.
98  *
99  * @note If the field is already present in the payload, it is replaced.
100  */
102  adv_data_flags_t flags = adv_data_flags_t::default_flags
103  )
104  {
105  ble_error_t res = _builder.setFlags(flags);
106  MBED_ASSERT(res == BLE_ERROR_NONE);
107  return *this;
108  }
109 
110  /**
111  * Add the advertising TX in the advertising payload.
112  *
113  * @param[in] txPower Transmission power level in dB.
114  *
115  * @return A reference to this object.
116  *
117  * @note If the field is already present in the payload, it is replaced.
118  */
120  {
121  ble_error_t res = _builder.setTxPowerAdvertised(txPower);
122  MBED_ASSERT(res == BLE_ERROR_NONE);
123  return *this;
124  }
125 
126  /**
127  * Add device name to the advertising payload.
128  *
129  * @note Data size for individual types cannot exceed 255 bytes.
130  *
131  * @param[in] name Null terminated string containing the name.
132  * @param[in] complete Complete local name if true, otherwise
133  *
134  * @return A reference to this object.
135  *
136  * @note If the field is already present in the payload, it is replaced.
137  */
138  AdvertisingDataSimpleBuilder &setName(const char *name, bool complete = true)
139  {
140  ble_error_t res = _builder.setName(name, complete);
141  MBED_ASSERT(res == BLE_ERROR_NONE);
142  return *this;
143  }
144 
145  /**
146  * Add manufacturer specific data to the advertising payload.
147  *
148  * @note Data size for individual types cannot exceed 255 bytes.
149  *
150  * @param[in] data New data to be added.
151  *
152  * @return a reference to this object.
153  */
155  {
156  ble_error_t res = _builder.setManufacturerSpecificData(data);
157  MBED_ASSERT(res == BLE_ERROR_NONE);
158  return *this;
159  }
160 
161  /**
162  * Add advertising interval to the payload. This field can only carry 2 bytes.
163  *
164  * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
165  *
166  * @return a reference to this object.
167  */
169  {
170  ble_error_t res = _builder.setAdvertisingInterval(interval);
171  MBED_ASSERT(res == BLE_ERROR_NONE);
172  return *this;
173  }
174 
175  /**
176  * Add connection interval preferences to the payload
177  *
178  * @param min Minimum connection interval to advertise.
179  * @param max Maximum connection interval to advertise.
180  *
181  * @return a reference to this object.
182  */
184  conn_interval_t min,
185  conn_interval_t max
186  )
187  {
188  ble_error_t res = _builder.setConnectionIntervalPreference(min, max);
189  MBED_ASSERT(res == BLE_ERROR_NONE);
190  return *this;
191  }
192 
193  /**
194  * Add service data to the advertising payload.
195  *
196  * @note Data size for individual types cannot exceed 255 bytes.
197  *
198  * @param[in] service UUID of the service.
199  * @param[in] data New data to be added.
200  *
201  * @return A reference to this object.
202  */
204  {
205  ble_error_t res = _builder.setServiceData(service, data);
206  MBED_ASSERT(res == BLE_ERROR_NONE);
207  return *this;
208  }
209 
210  /**
211  * Add local service ID to the advertising payload. If the data can't fit,
212  * no modification will take place.
213  *
214  * @note Data size for individual types cannot exceed 255 bytes.
215  *
216  * @param[in] data New data to be added.
217  * @param[in] complete True if this is a complete list.
218  *
219  * @return A reference to this object.
220  */
222  const UUID& data,
223  bool complete = true
224  )
225  {
226  ble_error_t res = _builder.setLocalServiceList(
227  mbed::make_Span(&data, 1), complete
228  );
229  MBED_ASSERT(res == BLE_ERROR_NONE);
230  return *this;
231  }
232 
233 
234  /**
235  * Add local service IDs to the advertising payload. If the data can't fit,
236  * no modification will take place.
237  *
238  * @note Data size for individual types cannot exceed 255 bytes.
239  *
240  * @param[in] data New data to be added.
241  * @param[in] complete True if this is a complete list.
242  *
243  * @return A reference to this object.
244  */
247  bool complete = true
248  )
249  {
250  ble_error_t res = _builder.setLocalServiceList(data, complete);
251  MBED_ASSERT(res == BLE_ERROR_NONE);
252  return *this;
253  }
254 
255  /**
256  * Add a UUID of a solicited service.
257  *
258  * @note Data size for individual types cannot exceed 255 bytes.
259  *
260  * @param[in] data List of 128 or 16 bit service UUIDs.
261  *
262  * @return A reference to this object.
263  */
265  {
266  ble_error_t res = _builder.setRequestedServiceList(mbed::make_Span(&data, 1));
267  MBED_ASSERT(res == BLE_ERROR_NONE);
268  return *this;
269  }
270 
271  /**
272  * Add a list of UUIDs of solicited services.
273  *
274  * @note Data size for individual types cannot exceed 255 bytes.
275  *
276  * @param[in] data List of 128 or 16 bit service UUIDs.
277  *
278  * @return A reference to this object.
279  */
281  {
282  ble_error_t res = _builder.setRequestedServiceList(data);
283  MBED_ASSERT(res == BLE_ERROR_NONE);
284  return *this;
285  }
286 
287  /**
288  * Add a new field into the payload. The operation fails if type is already present.
289  *
290  * @note Data size for individual types cannot exceed 255 bytes.
291  *
292  * @param[in] advDataType The type of the field to add.
293  * @param[in] fieldData Span of data to add.
294  *
295  * @return A reference to this object.
296  */
298  adv_data_type_t advDataType,
299  mbed::Span<const uint8_t> fieldData
300  )
301  {
302  ble_error_t res = _builder.addData(advDataType, fieldData);
303  MBED_ASSERT(res == BLE_ERROR_NONE);
304  return *this;
305  }
306 
307  /**
308  * Get the subspan of the buffer containing valid data.
309  *
310  * @return A Span containing the payload.
311  */
313  {
314  return _builder.getAdvertisingData();
315  }
316 
317 private:
318  uint8_t _buffer[DataSize];
319  AdvertisingDataBuilder _builder;
320 };
321 
322 /**
323  * @}
324  * @}
325  */
326 
327 } // namespace ble
328 
329 
330 #endif //BLE_GAP_SIMPLEADVERTISINGDATABUILDER_H
ble_error_t setAdvertisingInterval(adv_interval_t interval)
Add advertising interval to the payload.
ble_error_t setRequestedServiceList(mbed::Span< const UUID > data)
Add a list of UUIDs of solicited services.
Enumeration of values for the adv_data_type_t::APPEARANCE.
mbed::Span< const uint8_t > getAdvertisingData() const
Get the subspan of the buffer containing valid data.
ble_error_t setManufacturerSpecificData(mbed::Span< const uint8_t > data)
Add manufacturer-specific data to the advertising payload.
ble_error_t setConnectionIntervalPreference(conn_interval_t min, conn_interval_t max)
Add connection interval preferences to the payload.
ble_error_t setTxPowerAdvertised(advertising_power_t txPower)
Add the advertising TX in the advertising payload.
Span< T, Extent > make_Span(T *elements)
Generate a Span from a pointer to a C/C++ array.
Definition: Span.h:1034
ble_error_t addData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Add a new field into the payload.
AdvertisingDataSimpleBuilder & setFlags(adv_data_flags_t flags=adv_data_flags_t::default_flags)
Add BLE flags in the advertising payload.
AdvertisingDataSimpleBuilder()
Construct a AdvertisingDataSimpleBuilder.
AdvertisingDataSimpleBuilder & setServiceData(const UUID &service, mbed::Span< const uint8_t > data)
Add service data to the advertising payload.
Representation of a Universally Unique Identifier (UUID).
Definition: common/UUID.h:76
AdvertisingDataSimpleBuilder & setConnectionIntervalPreference(conn_interval_t min, conn_interval_t max)
Add connection interval preferences to the payload.
ble_error_t setName(const char *name, bool complete=true)
Add device name to the advertising payload.
ble_error_t setFlags(adv_data_flags_t flags=adv_data_flags_t::default_flags)
Add BLE flags in the advertising payload.
AdvertisingDataSimpleBuilder & setManufacturerSpecificData(mbed::Span< const uint8_t > data)
Add manufacturer specific data to the advertising payload.
Set of advertising flags.
Build advertising data.
#define MBED_ASSERT(expr)
MBED_ASSERT Declare runtime assertions: results in runtime error if condition is false.
Definition: mbed_assert.h:65
mbed::Span< const uint8_t > getAdvertisingData() const
Get the subspan of the buffer containing valid data.
AdvertisingDataSimpleBuilder & setRequestedService(const UUID &data)
Add a UUID of a solicited service.
AdvertisingDataSimpleBuilder & addData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Add a new field into the payload.
ble_error_t setAppearance(adv_data_appearance_t appearance)
Add device appearance in the advertising payload.
AdvertisingDataSimpleBuilder & setLocalServiceList(mbed::Span< const UUID > data, bool complete=true)
Add local service IDs to the advertising payload.
ble_error_t setLocalServiceList(mbed::Span< const UUID > data, bool complete=true)
Add local service IDs to the advertising payload.
AdvertisingDataSimpleBuilder & setTxPowerAdvertised(advertising_power_t txPower)
Add the advertising TX in the advertising payload.
AdvertisingDataSimpleBuilder & setAppearance(adv_data_appearance_t appearance)
Add device appearance in the advertising payload.
ble_error_t setServiceData(UUID service, mbed::Span< const uint8_t > data)
Add service data data to the advertising payload.
Entry namespace for all BLE API definitions.
AdvertisingDataSimpleBuilder & setLocalService(const UUID &data, bool complete=true)
Add local service ID to the advertising payload.
AdvertisingDataSimpleBuilder & setRequestedServiceList(mbed::Span< const UUID > data)
Add a list of UUIDs of solicited services.
AdvertisingDataSimpleBuilder & setAdvertisingInterval(adv_interval_t interval)
Add advertising interval to the payload.
AdvertisingDataSimpleBuilder & setName(const char *name, bool complete=true)
Add device name to the advertising payload.
ble_error_t
Error codes for the BLE API.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.