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...

AdvertisingParameters &	setType (advertising_type_t newAdvType, bool legacy)
	Update the advertising type and whether to use legacy PDU. More...

AdvertisingParameters &	setType (advertising_type_t newAdvType)
	Update the advertising type. More...

advertising_type_t	getType () const
	Return the advertising type. More...

AdvertisingParameters &	setPrimaryInterval (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...

AdvertisingParameters &	setPrimaryChannels (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...

AdvertisingParameters &	setOwnAddressType (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...

AdvertisingParameters &	setPeer (const address_t &address, target_peer_address_type_t addressType)
	Set peer address and type used during directed advertising. More...

const address_t &	getPeerAddress () 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...

AdvertisingParameters &	setFilter (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...

AdvertisingParameters &	setPhy (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...

AdvertisingParameters &	setTxPower (advertising_power_t txPower)
	Set the advertising TX power. More...

advertising_power_t	getTxPower () const
	Get the advertising TX power. More...

AdvertisingParameters &	setSecondaryMaxSkip (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...

AdvertisingParameters &	setScanRequestNotification (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...

AdvertisingParameters &	setUseLegacyPDU (bool enable=true)
	Use legacy PDU during advertising. More...

bool	getUseLegacyPDU () const
	Check if legacy PDU is used during advertising. More...

AdvertisingParameters &	includeTxPowerInHeader (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...

AdvertisingParameters &	setAnonymousAdvertising (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:

The Advertising mode modeled after advertising_type_t. It defines whether the device is connectable and scannable. You can set this value at construction time, update it with setType() and query it with getType().
Time interval between advertisement. You can set it at construction time, update it with setPrimaryInterval() and obtain it from getMinPrimaryInterval() and getMaxPrimaryInterval().

In addition, it is possible to adjust other parameters:

You can select the advertising channels with setPrimaryChannels() and queried them with getChannel37(), getChannel38() and getChannel39().
You can set the address type used by the local device with setOwnAddressType() and query it by getOwnAddressType().
You can set the filter policy for scan and connection requests with setFilter() and query it with getFilter().

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:

Control the advertising power with setTxPower().
Include the Tx power in advertising packet with includeTxPowerInHeader().
Set a secondary phy_t channel with setPhy().
Enable scan requests notification to let the application be aware of any incoming scan requests with setScanRequestNotification().
Advertise anonymously with setAnonymousAdvertising()

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,
        AdvertisingParameters()
            .setType(advertising_type_t::ADV_CONNECTABLE_UNDIRECTED)
            .setPrimaryInterval(millisecond_t(200), millisecond_t(500))
            .setOwnAddressType(own_address_type_t::RANDOM)
            .setUseLegacyPDU(false)
            .setPhy(phy_t::LE_1M, phy_t::LE_CODED)
    );
}

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]	advType	Type of advertising.
[in]	minInterval,maxInterval	Time 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]	useLegacyPDU	If 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]	advType	Type of advertising.
[in]	useLegacyPDU	If 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]	newAdvType	The new advertising type.
[in]	legacy	If 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] newAdvType The 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,max Time 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

channel37	Use channel 37.
channel38	Use channel 38.
channel39	Use 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

address	Peer's address bytes.
addressType	Peer'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

mode	Policy 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

primaryPhy	Primary advertising channels PHY.
secondaryPhy	Secondary 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

txPower Advertising 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

eventNumber Number 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

enable Enable 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

enable If 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

enable If 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

enable Advertising 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.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AdvertisingParameters() [1/2]

◆ AdvertisingParameters() [2/2]

Member Function Documentation

◆ setType() [1/2]

◆ setType() [2/2]

◆ getType()

◆ setPrimaryInterval()

◆ getMinPrimaryInterval()

◆ getMaxPrimaryInterval()

◆ setPrimaryChannels()

◆ getChannel37()

◆ getChannel38()

◆ getChannel39()

◆ setOwnAddressType()

◆ getOwnAddressType()

◆ setPeer()

◆ getPeerAddress()

◆ getPeerAddressType()

◆ setFilter()

◆ getFilter()

◆ setPhy()

◆ getPrimaryPhy()

◆ getSecondaryPhy()

◆ setTxPower()

◆ getTxPower()

◆ setSecondaryMaxSkip()

◆ getSecondaryMaxSkip()

◆ setScanRequestNotification()

◆ getScanRequestNotification()

◆ setUseLegacyPDU()

◆ getUseLegacyPDU()

◆ includeTxPowerInHeader()

◆ getTxPowerInHeader()

◆ setAnonymousAdvertising()

◆ getAnonymousAdvertising()