Mbed OS Reference
Loading...
Searching...
No Matches
AdvertisingParameters Class Reference

Parameters defining the advertising process. More...

#include <AdvertisingParameters.h>

Public Member Functions

 AdvertisingParameters (advertising_type_t advType=advertising_type_t::CONNECTABLE_UNDIRECTED, adv_interval_t minInterval=adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN), adv_interval_t maxInterval=adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX), bool useLegacyPDU=true)
 Construct an instance of GapAdvertisingParams. More...
 
 AdvertisingParameters (advertising_type_t advType, bool useLegacyPDU)
 Construct an instance of GapAdvertisingParams. More...
 
AdvertisingParameterssetType (advertising_type_t newAdvType, bool legacy)
 Update the advertising type and whether to use legacy PDU. More...
 
AdvertisingParameterssetType (advertising_type_t newAdvType)
 Update the advertising type. More...
 
advertising_type_t getType () const
 Return the advertising type. More...
 
AdvertisingParameterssetPrimaryInterval (adv_interval_t min, adv_interval_t max)
 Set the advertising intervals on the primary channels. More...
 
adv_interval_t getMinPrimaryInterval () const
 Get the minimum advertising intervals on the primary channels. More...
 
adv_interval_t getMaxPrimaryInterval () const
 Get the maximum advertising intervals on the primary channels. More...
 
AdvertisingParameterssetPrimaryChannels (bool channel37, bool channel38, bool channel39)
 Set which channels are to be used for primary advertising. More...
 
bool getChannel37 () const
 Check if channel 37 is used for primary advertising. More...
 
bool getChannel38 () const
 Check if channel 38 is used for primary advertising. More...
 
bool getChannel39 () const
 Check if channel 39 is used for primary advertising. More...
 
AdvertisingParameterssetOwnAddressType (own_address_type_t addressType)
 Get what type of address is to be used as your own address during advertising. More...
 
own_address_type_t getOwnAddressType () const
 Get what type of address is to be used as your own address during advertising. More...
 
AdvertisingParameterssetPeer (const address_t &address, target_peer_address_type_t addressType)
 Set peer address and type used during directed advertising. More...
 
const address_tgetPeerAddress () const
 Get the peer address used during directed advertising. More...
 
target_peer_address_type_t getPeerAddressType () const
 Get the peer address type used during directed advertising. More...
 
AdvertisingParameterssetFilter (advertising_filter_policy_t mode)
 Set the filter policy of whitelist use during advertising;. More...
 
advertising_filter_policy_t getFilter () const
 Get the filter policy of whitelist use during advertising;. More...
 
AdvertisingParameterssetPhy (phy_t primaryPhy, phy_t secondaryPhy)
 Get PHYs used on primary and secondary advertising channels. More...
 
phy_t getPrimaryPhy () const
 Get PHY used for primary advertising. More...
 
phy_t getSecondaryPhy () const
 Get PHY used for secondary advertising. More...
 
AdvertisingParameterssetTxPower (advertising_power_t txPower)
 Set the advertising TX power. More...
 
advertising_power_t getTxPower () const
 Get the advertising TX power. More...
 
AdvertisingParameterssetSecondaryMaxSkip (uint8_t eventNumber)
 Set how many events can be skipped on the secondary channel. More...
 
uint8_t getSecondaryMaxSkip () const
 Return how many events can be skipped on the secondary channel. More...
 
AdvertisingParameterssetScanRequestNotification (bool enable=true)
 Enabled or disable the callback that notifies the user about a scan request. More...
 
bool getScanRequestNotification () const
 Return of the callback for scan request is enabled. More...
 
AdvertisingParameterssetUseLegacyPDU (bool enable=true)
 Use legacy PDU during advertising. More...
 
bool getUseLegacyPDU () const
 Check if legacy PDU is used during advertising. More...
 
AdvertisingParametersincludeTxPowerInHeader (bool enable=true)
 Set if TX power should be included in the header. More...
 
bool getTxPowerInHeader () const
 Check if TX power should be included in the header. More...
 
AdvertisingParameterssetAnonymousAdvertising (bool enable)
 Advertise without your own address. More...
 
bool getAnonymousAdvertising () const
 Check if advertising is anonymous. More...
 

Detailed Description

Parameters defining the advertising process.

Legacy advertising:

Advertising parameters for legacy advertising are a mainly defined by a pair of values:

In addition, it is possible to adjust other parameters:

For directed advertising, you can set the address of the target with the help of setPeer() and query it with getPeerAddress() and getPeerAddressType().

Extended advertising:

To use extended advertising features, first disable legacy advertising with setUseLegacyPDU().

Extended advertising adds new features to BLE advertising:

Fluent interface:

This API is designed for usability. You can construct it and pass it in place. To achieve this, the fluent interface pattern is used. Every setter returns a reference to the object modified and can be chained.

void setAdvertisingParameters(ble::PalGap& gap) {
using namespace ble;
gap.setAdvertisingParameters(
LEGACY_ADVERTISING_HANDLE,
.setType(advertising_type_t::ADV_CONNECTABLE_UNDIRECTED)
.setOwnAddressType(own_address_type_t::RANDOM)
);
}
Parameters defining the advertising process.
AdvertisingParameters & setOwnAddressType(own_address_type_t addressType)
Get what type of address is to be used as your own address during advertising.
AdvertisingParameters & setPhy(phy_t primaryPhy, phy_t secondaryPhy)
Get PHYs used on primary and secondary advertising channels.
AdvertisingParameters & setType(advertising_type_t newAdvType, bool legacy)
Update the advertising type and whether to use legacy PDU.
AdvertisingParameters & setPrimaryInterval(adv_interval_t min, adv_interval_t max)
Set the advertising intervals on the primary channels.
AdvertisingParameters & setUseLegacyPDU(bool enable=true)
Use legacy PDU during advertising.
Entry namespace for all BLE API definitions.
Duration< uint32_t, 1000 *microsecond_t::TIME_BASE > millisecond_t
Type that represents milliseconds.
Definition: Duration.h:303
@ LE_1M
1Mbit/s LE.
@ LE_CODED
LE Coded PHY.
See also
ble::Gap::createAdvertisingSet(), ble::Gap::setAdvertisingParameters()

Definition at line 99 of file AdvertisingParameters.h.

Constructor & Destructor Documentation

◆ AdvertisingParameters() [1/2]

AdvertisingParameters ( advertising_type_t  advType = advertising_type_t::CONNECTABLE_UNDIRECTED,
adv_interval_t  minInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN),
adv_interval_t  maxInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX),
bool  useLegacyPDU = true 
)

Construct an instance of GapAdvertisingParams.

Parameters
[in]advTypeType of advertising.
[in]minInterval,maxIntervalTime interval between two advertisement. A range is provided to the LE subsystem, so it can adjust the advertising interval with other transmission happening on the BLE radio.
[in]useLegacyPDUIf true legacy PDU shall be used for advertising.
Note
If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used you must use legacy PDU.
If values in input are out of range, they will be normalized.
If type selected is incompatible with non legacy PDU, legacy PDU will be used.

Definition at line 136 of file AdvertisingParameters.h.

◆ AdvertisingParameters() [2/2]

AdvertisingParameters ( advertising_type_t  advType,
bool  useLegacyPDU 
)

Construct an instance of GapAdvertisingParams.

Parameters
[in]advTypeType of advertising.
[in]useLegacyPDUIf true legacy PDU shall be used for advertising.
Note
If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used you must use legacy PDU.
If type selected is incompatible with non legacy PDU, legacy PDU will be used.

Definition at line 175 of file AdvertisingParameters.h.

Member Function Documentation

◆ setType() [1/2]

AdvertisingParameters & setType ( advertising_type_t  newAdvType,
bool  legacy 
)

Update the advertising type and whether to use legacy PDU.

Note
If legacy PDU is not used then you cannot use CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
Parameters
[in]newAdvTypeThe new advertising type.
[in]legacyIf true, legacy PDU will be used.
Returns
reference to this object.

Definition at line 214 of file AdvertisingParameters.h.

◆ setType() [2/2]

AdvertisingParameters & setType ( advertising_type_t  newAdvType)

Update the advertising type.

Note
If legacy PDU is not used then you cannot use CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
Parameters
[in]newAdvTypeThe new advertising type.
Returns
reference to this object.

Definition at line 236 of file AdvertisingParameters.h.

◆ getType()

advertising_type_t getType ( ) const

Return the advertising type.

Returns
Advertising type.

Definition at line 252 of file AdvertisingParameters.h.

◆ setPrimaryInterval()

AdvertisingParameters & setPrimaryInterval ( adv_interval_t  min,
adv_interval_t  max 
)

Set the advertising intervals on the primary channels.

Parameters
[in]min,maxTime interval between two advertisements. A range is provided to the LE subsystem, so it can adjust the advertising interval with other transmission happening on the BLE radio.
Returns
reference to this object.

Definition at line 265 of file AdvertisingParameters.h.

◆ getMinPrimaryInterval()

adv_interval_t getMinPrimaryInterval ( ) const

Get the minimum advertising intervals on the primary channels.

Returns
The lower bound of the primary interval selected.

Definition at line 278 of file AdvertisingParameters.h.

◆ getMaxPrimaryInterval()

adv_interval_t getMaxPrimaryInterval ( ) const

Get the maximum advertising intervals on the primary channels.

Returns
The higher bound of the primary interval selected.

Definition at line 287 of file AdvertisingParameters.h.

◆ setPrimaryChannels()

AdvertisingParameters & setPrimaryChannels ( bool  channel37,
bool  channel38,
bool  channel39 
)

Set which channels are to be used for primary advertising.

At least must be used. If all are set to disabled, all channels will be used.

Parameters
channel37Use channel 37.
channel38Use channel 38.
channel39Use channel 39.
Returns
a reference to this object.

Definition at line 301 of file AdvertisingParameters.h.

◆ getChannel37()

bool getChannel37 ( ) const

Check if channel 37 is used for primary advertising.

Returns
True if channel used.

Definition at line 318 of file AdvertisingParameters.h.

◆ getChannel38()

bool getChannel38 ( ) const

Check if channel 38 is used for primary advertising.

Returns
True if channel used.

Definition at line 327 of file AdvertisingParameters.h.

◆ getChannel39()

bool getChannel39 ( ) const

Check if channel 39 is used for primary advertising.

Returns
True if channel used.

Definition at line 336 of file AdvertisingParameters.h.

◆ setOwnAddressType()

AdvertisingParameters & setOwnAddressType ( own_address_type_t  addressType)

Get what type of address is to be used as your own address during advertising.

Returns
a reference to this object.

Definition at line 345 of file AdvertisingParameters.h.

◆ getOwnAddressType()

own_address_type_t getOwnAddressType ( ) const

Get what type of address is to be used as your own address during advertising.

Returns
Addres tpe used.

Definition at line 355 of file AdvertisingParameters.h.

◆ setPeer()

AdvertisingParameters & setPeer ( const address_t address,
target_peer_address_type_t  addressType 
)

Set peer address and type used during directed advertising.

Parameters
addressPeer's address bytes.
addressTypePeer's address type.
Returns
a reference to this object.

Definition at line 367 of file AdvertisingParameters.h.

◆ getPeerAddress()

const address_t & getPeerAddress ( ) const

Get the peer address used during directed advertising.

Returns
Address of the peer targeted by directed advertising.

Definition at line 381 of file AdvertisingParameters.h.

◆ getPeerAddressType()

target_peer_address_type_t getPeerAddressType ( ) const

Get the peer address type used during directed advertising.

Returns
The type of address of the peer targeted by directed advertising.

Definition at line 391 of file AdvertisingParameters.h.

◆ setFilter()

AdvertisingParameters & setFilter ( advertising_filter_policy_t  mode)

Set the filter policy of whitelist use during advertising;.

Parameters
modePolicy to use.
Returns
A reference to this object.

Definition at line 402 of file AdvertisingParameters.h.

◆ getFilter()

advertising_filter_policy_t getFilter ( ) const

Get the filter policy of whitelist use during advertising;.

Returns
Policy used.

Definition at line 412 of file AdvertisingParameters.h.

◆ setPhy()

AdvertisingParameters & setPhy ( phy_t  primaryPhy,
phy_t  secondaryPhy 
)

Get PHYs used on primary and secondary advertising channels.

Parameters
primaryPhyPrimary advertising channels PHY.
secondaryPhySecondary advertising channels PHY.
Returns
A reference to this.

Definition at line 430 of file AdvertisingParameters.h.

◆ getPrimaryPhy()

phy_t getPrimaryPhy ( ) const

Get PHY used for primary advertising.

Returns
PHY used for primary advertising.

Definition at line 441 of file AdvertisingParameters.h.

◆ getSecondaryPhy()

phy_t getSecondaryPhy ( ) const

Get PHY used for secondary advertising.

Returns
PHY used for secondary advertising.

Definition at line 450 of file AdvertisingParameters.h.

◆ setTxPower()

AdvertisingParameters & setTxPower ( advertising_power_t  txPower)

Set the advertising TX power.

Parameters
txPowerAdvertising TX power.
Returns
A reference to this object.

Definition at line 461 of file AdvertisingParameters.h.

◆ getTxPower()

advertising_power_t getTxPower ( ) const

Get the advertising TX power.

Returns
Advertising TX power.

Definition at line 471 of file AdvertisingParameters.h.

◆ setSecondaryMaxSkip()

AdvertisingParameters & setSecondaryMaxSkip ( uint8_t  eventNumber)

Set how many events can be skipped on the secondary channel.

Parameters
eventNumberNumber of events that can be skipped.
Returns
A reference to this object.

Definition at line 482 of file AdvertisingParameters.h.

◆ getSecondaryMaxSkip()

uint8_t getSecondaryMaxSkip ( ) const

Return how many events can be skipped on the secondary channel.

Returns
How many events can be skipped on the secondary channel.

Definition at line 492 of file AdvertisingParameters.h.

◆ setScanRequestNotification()

AdvertisingParameters & setScanRequestNotification ( bool  enable = true)

Enabled or disable the callback that notifies the user about a scan request.

Parameters
enableEnable callback if true.
Returns
A reference to this object.
See also
ble::Gap::EventHandler::onScanRequestReceived()

Definition at line 505 of file AdvertisingParameters.h.

◆ getScanRequestNotification()

bool getScanRequestNotification ( ) const

Return of the callback for scan request is enabled.

Returns
True if callback is enabled.

Definition at line 515 of file AdvertisingParameters.h.

◆ setUseLegacyPDU()

AdvertisingParameters & setUseLegacyPDU ( bool  enable = true)

Use legacy PDU during advertising.

Parameters
enableIf true, legacy PDU will be used.
Note
If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used you must use legacy PDU.
Returns
A reference to this object.

Definition at line 529 of file AdvertisingParameters.h.

◆ getUseLegacyPDU()

bool getUseLegacyPDU ( ) const

Check if legacy PDU is used during advertising.

Returns
True legacy PDU will be used.

Definition at line 545 of file AdvertisingParameters.h.

◆ includeTxPowerInHeader()

AdvertisingParameters & includeTxPowerInHeader ( bool  enable = true)

Set if TX power should be included in the header.

Parameters
enableIf true, include the TX power in the header.
Returns
A reference to this object.

Definition at line 556 of file AdvertisingParameters.h.

◆ getTxPowerInHeader()

bool getTxPowerInHeader ( ) const

Check if TX power should be included in the header.

Returns
True if TX power is included in the header.

Definition at line 566 of file AdvertisingParameters.h.

◆ setAnonymousAdvertising()

AdvertisingParameters & setAnonymousAdvertising ( bool  enable)

Advertise without your own address.

Parameters
enableAdvertising anonymous if true.
Note
You may not use anonymous advertising with periodic advertising on the same set.
Returns
reference to this object.

Definition at line 579 of file AdvertisingParameters.h.

◆ getAnonymousAdvertising()

bool getAnonymousAdvertising ( ) const

Check if advertising is anonymous.

Returns
True if advertising is anonymous.

Definition at line 589 of file AdvertisingParameters.h.