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