Mistake on this page?
Report an issue in GitHub or email us
AdvertisingDataBuilder.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 MBED_GAP_ADVERTISING_DATA_H__
18 #define MBED_GAP_ADVERTISING_DATA_H__
19 
20 #include <stdint.h>
21 #include <string.h>
22 #include <stdlib.h>
23 
24 #include "platform/Span.h"
25 #include "platform/NonCopyable.h"
26 
27 #include "ble/blecommon.h"
28 #include "UUID.h"
29 #include "ble/gap/AdvertisingDataTypes.h"
30 #include "ble/gap/Types.h"
31 
32 namespace ble {
33 
34 /**
35  * @addtogroup ble
36  * @{
37  * @addtogroup gap
38  * @{
39  */
40 
41 /**
42  * Build advertising data.
43  *
44  * The builder accepts an array of bytes in input and returns the result of the
45  * construction with getAdvertisingData().
46  */
48 public:
49  /** Advertising data needs a user-provided buffer to store the data.
50  *
51  * @param buffer Buffer used to store the data.
52  * @note Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.
53  */
55 
56  /** Advertising data needs a user provided buffer to store the data.
57  *
58  * @param buffer Pointer to buffer to be used for storing advertising data.
59  * @param buffer_size Size of the buffer.
60  * @note Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.
61  */
62  AdvertisingDataBuilder(uint8_t *buffer, size_t buffer_size);
63 
64  /**
65  * Get the subspan of the buffer containing valid data.
66  *
67  * @return A Span containing the payload.
68  */
70 
71  /**
72  * Add a new field into the payload. Returns an error if type is already present.
73  *
74  * @note Data size for individual types cannot exceed 255 bytes.
75  *
76  * @param[in] advDataType The type of the field to add.
77  * @param[in] fieldData Span of data to add.
78  *
79  * @retval BLE_ERROR_NONE on success.
80  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
81  * @retval BLE_ERROR_OPERATION_NOT_PERMITTED if data type already present.
82  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
83  */
85  adv_data_type_t advDataType,
87  );
88 
89  /**
90  * Replace a new field into the payload. Will fail if type is not already present.
91  *
92  * @note Data size for individual types cannot exceed 255 bytes.
93  *
94  * @param[in] advDataType The type of the field to add.
95  * @param[in] fieldData Span of data to add.
96  *
97  * @retval BLE_ERROR_NONE on success.
98  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
99  * @retval BLE_ERROR_NOT_FOUND if data type not present.
100  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
101  */
103  adv_data_type_t advDataType,
104  mbed::Span<const uint8_t> fieldData
105  );
106 
107  /**
108  * Append data to an existing field in the payload. Will fail if type is not already
109  * present.
110  *
111  * @note Data size for individual types cannot exceed 255 bytes.
112  *
113  * @param[in] advDataType The type of the field to add.
114  * @param[in] fieldData Span of data to add.
115  *
116  * @retval BLE_ERROR_NONE on success.
117  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
118  * @retval BLE_ERROR_NOT_FOUND if data type not present.
119  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
120  */
122  adv_data_type_t advDataType,
123  mbed::Span<const uint8_t> fieldData
124  );
125 
126  /**
127  * Remove existing date of given type. Will return an error if type is not present.
128  *
129  * @param[in] advDataType The type of the field to remove.
130  *
131  * @return BLE_ERROR_NONE returned on success, BLE_ERROR_INVALID_PARAM if field doesn't exist
132  */
134 
135  /**
136  * Adds a new field into the payload. If the supplied advertising data type is
137  * already present in the advertising payload, then the value is replaced.
138  *
139  * @note Data size for individual types cannot exceed 255 bytes.
140  *
141  * @param[in] advDataType The type of the field to add.
142  * @param[in] fieldData Span of data to add.
143  *
144  * @retval BLE_ERROR_NONE on success.
145  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
146  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
147  */
149  adv_data_type_t advDataType,
150  mbed::Span<const uint8_t> fieldData
151  );
152 
153  /**
154  * Adds a new field into the payload. If the supplied advertising data type is
155  * already present in the advertising payload, then the value is replaced.
156  *
157  * @note Data size for individual types cannot exceed 255 bytes.
158  *
159  * @param[in] advDataType The type of the field to add.
160  * @param[in] fieldData Span of data to add.
161  *
162  * @retval BLE_ERROR_NONE on success.
163  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
164  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
165  */
167  adv_data_type_t advDataType,
168  mbed::Span<const uint8_t> fieldData
169  );
170 
171  /**
172  * Clears the advertising data payload.
173  *
174  * @post getPayloadLen() returns 0.
175  */
176  void clear();
177 
178  /**
179  * Add device appearance in the advertising payload.
180  *
181  * @param[in] appearance The appearance to advertise.
182  *
183  * @retval BLE_ERROR_NONE on success.
184  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
185  *
186  * @note This call is equivalent to calling addOrReplaceData() with
187  * adv_data_type_t::APPEARANCE as the field type.
188  */
190 
191  /**
192  * Add BLE flags in the advertising payload.
193  *
194  * @param[in] flags Bitfield describing the capability of the device. See
195  * allowed flags in Flags_t.
196  *
197  * @retval BLE_ERROR_NONE on success.
198  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
199  *
200  * @note This call is equivalent to calling addOrReplaceData() with
201  * adv_data_type_t::FLAGS as the field type.
202  */
204  adv_data_flags_t flags = adv_data_flags_t::default_flags
205  );
206 
207  /**
208  * Add the advertising TX in the advertising payload.
209  *
210  * @param[in] txPower Transmission power level in dB.
211  *
212  * @retval BLE_ERROR_NONE on success.
213  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
214  *
215  * @note This call is equivalent to calling addOrReplaceData() with
216  * adv_data_type_t::TX_POWER_LEVEL as the field type.
217  */
219 
220  /**
221  * Add device name to the advertising payload.
222  *
223  * @note Data size for individual types cannot exceed 255 bytes.
224  *
225  * @param[in] name Null terminated string containing the name.
226  * @param[in] complete Complete local name if true, otherwise
227  *
228  * @retval BLE_ERROR_NONE on success.
229  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
230  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
231  */
232  ble_error_t setName(const char *name, bool complete = true);
233 
234  /**
235  * Add manufacturer-specific data to the advertising payload.
236  *
237  * @note Data size for individual types cannot exceed 255 bytes.
238  *
239  * @param[in] data New data to be added.
240  *
241  * @retval BLE_ERROR_NONE on success.
242  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
243  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual
244  * data field or the data is too small (must contain
245  * 2 bytes of manufacturer ID)
246  */
248 
249  /**
250  * Add advertising interval to the payload. This field can only carry 2 bytes.
251  *
252  * @param interval Interval to advertise. Cannot be larger than 0xFFFF.
253 
254  * @retval BLE_ERROR_NONE on success.
255  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
256  * @retval BLE_ERROR_INVALID_PARAM if interval value outside of valid range.
257  */
259 
260  /**
261  * Add connection interval preferences to the payload
262  *
263  * @param min Minimum connection interval to advertise.
264  * @param max Maximum connection interval to advertise.
265 
266  * @retval BLE_ERROR_NONE on success.
267  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
268  */
270  conn_interval_t min,
271  conn_interval_t max
272  );
273 
274  /**
275  * Add service data data to the advertising payload.
276  *
277  * @note Data size for individual types cannot exceed 255 bytes.
278  *
279  * @param[in] service UUID of the service.
280  * @param[in] data New data to be added.
281  *
282  * @retval BLE_ERROR_NONE on success.
283  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
284  * @retval BLE_ERROR_INVALID_PARAM if size of data is too big too fit in an individual data field.
285  */
287 
288  /**
289  * Add local service IDs to the advertising payload. If the data can't fit,
290  * no modification will take place.
291  *
292  * @note Data size for individual types cannot exceed 255 bytes.
293  *
294  * @param[in] data New data to be added.
295  * @param[in] complete True if this is a complete list.
296  *
297  * @retval BLE_ERROR_NONE on success.
298  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
299  * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
300  */
303  bool complete = true
304  );
305 
306  /**
307  * Add a list of UUIDs of solicited services.
308  *
309  * @note Data size for individual types cannot exceed 255 bytes.
310  *
311  * @param[in] data List of 128 or 16 bit service UUIDs.
312  *
313  * @retval BLE_ERROR_NONE on success.
314  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
315  * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
316  */
318 
319  /**
320  * Return a span of data containing the the type of data requested.
321  *
322  * @param[out] data Span used to return the requested data.
323  * @param[in] advDataType Data type to return.
324  *
325  * @return BLE_ERROR_NONE if data was found and BLE_ERROR_NOT_FOUND if not.
326  */
329  adv_data_type_t advDataType
330  );
331 
332 private:
333  /**
334  * Search advertisement data for a specific field.
335  *
336  * @param[in] type The type of the field to find.
337  *
338  * @return A pointer to the first element in the field if found. The first
339  * element being the length of the field followed by the value of the field.
340  * NULL if the field is not present in the payload.
341  */
342  uint8_t *findField(adv_data_type_t type);
343 
344  /**
345  * Get field size (includes type and size bytes)
346  *
347  * @param type The field type.
348  *
349  * @return Size of the whole field including type and size bytes.
350  */
351  uint8_t getFieldSize(adv_data_type_t type);
352 
353  /**
354  * Append advertising data based on the specified type.
355  *
356  * @note Data size for individual types cannot exceed 255 bytes.
357  *
358  * @param[in] advDataType Type of the new data.
359  * @param[in] fieldData Span of data to add.
360  *
361  * @retval BLE_ERROR_NONE on success.
362  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
363  */
364  ble_error_t addField(
365  adv_data_type_t advDataType,
366  mbed::Span<const uint8_t> fieldData
367  );
368 
369  /**
370  * Append data to a field in the advertising payload.
371  *
372  * @note Data size for individual types cannot exceed 255 bytes.
373  *
374  * @param[in] fieldData Span of data to add.
375  * @param[in] field Pointer to the field in the advertising buffer.
376  *
377  * @return BLE_ERROR_NONE on success.
378  */
379  ble_error_t appendToField(
380  mbed::Span<const uint8_t> fieldData,
381  uint8_t *field
382  );
383 
384  /**
385  * Update in place the value of a field in the advertising payload.
386  *
387  * @note Data size for individual types cannot exceed 255 bytes.
388  *
389  * @param[in] advDataType Type of the new data.
390  * @param[in] fieldData Span of data to add.
391  * @param[in] field Pointer to the field of type @p advDataType in the
392  * advertising buffer.
393  *
394  * @retval BLE_ERROR_NONE on success.
395  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
396  */
397  ble_error_t replaceField(
398  adv_data_type_t advDataType,
399  mbed::Span<const uint8_t> fieldData,
400  uint8_t *field
401  );
402 
403  /**
404  * Remove the field.
405  *
406  * @param[in] field Pointer to the field in the advertising buffer.
407  *
408  * @return BLE_ERROR_NONE on success.
409  */
410  ble_error_t removeField(uint8_t *field);
411 
412  /**
413  * Add a list of UUIDs to given types.
414  *
415  * @note Data size for individual types cannot exceed 255 bytes.
416  *
417  * @param[in] data List of 128 or 16 bit service UUIDs.
418  * @param[in] shortType Type of field to add the short UUIDs to.
419  * @param[in] longType Type of field to add the long UUIDs to.
420  *
421  * @retval BLE_ERROR_NONE on success.
422  * @retval BLE_ERROR_BUFFER_OVERFLOW if buffer is too small to contain the new data.
423  * @retval BLE_ERROR_INVALID_PARAM if number of UUIDs of any one type is too high.
424  */
425  ble_error_t setUUIDData(
427  adv_data_type_t shortType,
428  adv_data_type_t longType
429  );
430 
431 private:
432  /** The memory backing the the data provided by the user. */
433  mbed::Span<uint8_t> _buffer;
434 
435  /** Length of the data added to the advertising buffer. */
436  uint8_t _payload_length;
437 };
438 
439 /**
440  * @}
441  * @}
442  */
443 
444 } // namespace ble
445 
446 #endif /* ifndef MBED_GAP_ADVERTISING_DATA_H__ */
ble_error_t setAdvertisingInterval(adv_interval_t interval)
Add advertising interval to the payload.
ble_error_t addOrAppendData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Adds a new field into 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.
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.
ble_error_t getData(mbed::Span< const uint8_t > &data, adv_data_type_t advDataType)
Return a span of data containing the the type of data requested.
ble_error_t addData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Add a new field into the payload.
void clear()
Clears the advertising data payload.
Representation of a Universally Unique Identifier (UUID).
Definition: UUID.h:74
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
ble_error_t removeData(adv_data_type_t advDataType)
Remove existing date of given type.
Set of advertising flags.
Build advertising data.
ble_error_t replaceData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Replace a new field into the payload.
ble_error_t appendData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Append data to an existing field in the payload.
mbed::Span< const uint8_t > getAdvertisingData() const
Get the subspan of the buffer containing valid data.
ble_error_t setAppearance(adv_data_appearance_t appearance)
Add device appearance in the advertising payload.
ble_error_t setLocalServiceList(mbed::Span< const UUID > data, bool complete=true)
Add local service IDs to the advertising payload.
ble_error_t addOrReplaceData(adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
Adds a new field into the 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.
Definition: ArrayView.h:37
AdvertisingDataBuilder(mbed::Span< uint8_t > buffer)
Advertising data needs a user-provided buffer to store the data.
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.