ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

BLE: Improve ble::Gap documentation.

pull/8738/head
Vincent Coubard 2018-11-26 11:50:45 +00:00
parent bee115c39e
commit d3d93e1ef9
1 changed files with 18 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
features/FEATURE_BLE/ble/gap/Gap.h
View File

@ -71,7 +71,7 @@ namespace ble {
* @par Advertising * @par Advertising
* *
* Advertising consists of broadcasting at a regular interval a small amount of * Advertising consists of broadcasting at a regular interval a small amount of
* data containing valuable informations about the device. These packets may be * data containing valuable information about the device. These packets may be
* scanned by peer devices listening on BLE advertising channels. * scanned by peer devices listening on BLE advertising channels.
* *
* Scanners may also request additional information from a device advertising by * Scanners may also request additional information from a device advertising by
@ -84,16 +84,22 @@ namespace ble {
* updated the data will take effect from the next advertising event. * updated the data will take effect from the next advertising event.
* *
* To create a valid advertising payload and scan response you may use * To create a valid advertising payload and scan response you may use
* AdvertisingDataBuilder(). You must first allocate memory and crate an mbed::Span and * AdvertisingDataBuilder. You must first allocate memory and create an mbed::Span and
* pass that into the AdvertisingDataBuilder which will only be able to add as much * pass that into the AdvertisingDataBuilder which will only be able to add as much
* data as fits in the provided buffer. The builder will accept any size of the buffer * data as fits in the provided buffer. The builder will accept any size of the buffer
* but for the created data to be usable it must be smaller than the maximum data * but for the created data to be usable it must be smaller than the maximum data
* length returned from getMaxAdvertisingDataLength(). * length returned from getMaxAdvertisingDataLength().
* *
* @note The maximum size of data depends on the controller and its support for * Another option is to use AdvertisingDataSimpleBuilder that allocates memory
* extended advertising however even if the controller supports larger data lengths if * on the stack and offers a fluent interface at the expense of a reduced set of
* you wish to be compatible with older devices you may wish to use legacy * APIs and error management options.
* advertising and should not use payloads larger than LEGACY_ADVERTISING_MAX_SIZE. *
* @note Prior to Bluetooth 5; advertising and scanning payload size were limited
* to LEGACY_ADVERTISING_MAX_SIZE. It changed with Bluetooth 5 and now the maximum
* size of data that can be advertised depends on the controller. If you wish
* to be compatible with older devices you may wish to advertise with the
* LEGACY_ADVERTISING_HANDLE and uses payloads no larger than LEGACY_ADVERTISING_MAX_SIZE
* with that advertising set.
* *
* @par Extended advertising * @par Extended advertising
* *
@ -150,8 +156,10 @@ namespace ble {
* they are not actively advertising right now so it's important to destroy the set * they are not actively advertising right now so it's important to destroy the set
* when you're done with it (or reuse it in the next advertisement). * when you're done with it (or reuse it in the next advertisement).
* *
* Periodic advertising and extended advertising share the same set. For periodic * Periodic advertising and extended advertising share the same set but not the same
* advertising to start the extended advertising of the same set must also be active. * data. Periodic advertising synchronization information are carried out by
* extended advertising therefore to let other devices be aware that your device
* exposes periodic advertising you should start extended advertising of the set.
* Subsequently you may disable extended advertising and the periodic advertising * Subsequently you may disable extended advertising and the periodic advertising
* will continue. If you start periodic advertising while extended advertising is * will continue. If you start periodic advertising while extended advertising is
* inactive, periodic advertising will not start until you start extended advertising * inactive, periodic advertising will not start until you start extended advertising
@ -1077,8 +1085,8 @@ public:
); );
/** /**
* Default peripheral privacy configuration. * Default peripheral privacy configuration.
*/ */
static const peripheral_privacy_configuration_t static const peripheral_privacy_configuration_t
default_peripheral_privacy_configuration; default_peripheral_privacy_configuration;