Perform and manage BLE advertising. More...

#include <NimBLEAdvertising.h>

Public Member Functions
	NimBLEAdvertising ()
	Construct a default advertising object.

bool	start (uint32_t duration=0, const NimBLEAddress *dirAddr=nullptr)
	Start advertising.

void	setAdvertisingCompleteCallback (advCompleteCB_t callback)
	Set the callback to be invoked when advertising stops.

bool	stop ()
	Stop advertising.

bool	setConnectableMode (uint8_t mode)
	Set the type of connectable mode to advertise.

bool	setDiscoverableMode (uint8_t mode)
	Set the discoverable mode to use.

bool	reset ()
	Stops the current advertising and resets the advertising data to the default values.

bool	isAdvertising ()
	Check if currently advertising.

void	setScanFilter (bool scanRequestWhitelistOnly, bool connectWhitelistOnly)
	Set the filtering for the scan filter.

void	enableScanResponse (bool enable)
	Enable scan response data.

void	setAdvertisingInterval (uint16_t interval)
	Set the advertising interval.

void	setMaxInterval (uint16_t maxInterval)
	Set the maximum advertising interval.

void	setMinInterval (uint16_t minInterval)
	Set the minimum advertising interval.

bool	setAdvertisementData (const NimBLEAdvertisementData &advertisementData)
	Set the advertisement data that is to be broadcast in a regular advertisement.

bool	setScanResponseData (const NimBLEAdvertisementData &advertisementData)
	Set the data that is to be provided in a scan response.

const NimBLEAdvertisementData &	getAdvertisementData ()
	Get the current advertisement data.

const NimBLEAdvertisementData &	getScanData ()
	Get the current scan response data.

void	clearData ()
	Clear the advertisement and scan response data and set the flags to BLE_HS_ADV_F_DISC_GEN.

bool	refreshAdvertisingData ()
	Refresh advertsing data dynamically without stop/start cycle. For instance allows refreshing manufacturer data dynamically.

bool	addServiceUUID (const NimBLEUUID &serviceUUID)
	Add a service uuid to exposed list of services.

bool	addServiceUUID (const char *serviceUUID)
	Add a service uuid to exposed list of services.

bool	removeServiceUUID (const NimBLEUUID &serviceUUID)
	Remove a service UUID from the advertisement.

bool	removeServiceUUID (const char *serviceUUID)
	Remove a service UUID from the advertisement.

bool	removeServices ()
	Remove all service UUIDs from the advertisement.

bool	setAppearance (uint16_t appearance)
	Set the device appearance in the advertising data.

bool	setPreferredParams (uint16_t minInterval, uint16_t maxInterval)
	Set the preferred min and max connection intervals to advertise.

bool	addTxPower ()
	Add the transmission power level to the advertisement packet.

bool	setName (const std::string &name)
	Set the advertised name of the device.

bool	setManufacturerData (const uint8_t *data, size_t length)
	Set the advertised manufacturer data.

bool	setManufacturerData (const std::string &data)
	Set the advertised manufacturer data.

bool	setManufacturerData (const std::vector< uint8_t > &data)
	Set the advertised manufacturer data.

bool	setURI (const std::string &uri)
	Set the advertised URI.

bool	setServiceData (const NimBLEUUID &uuid, const uint8_t *data, size_t length)
	Set the service data advertised for the UUID.

bool	setServiceData (const NimBLEUUID &uuid, const std::string &data)
	Set the service data advertised for the UUID.

bool	setServiceData (const NimBLEUUID &uuid, const std::vector< uint8_t > &data)
	Set the service data advertised for the UUID.

Detailed Description

Perform and manage BLE advertising.

A BLE server will want to perform advertising in order to make itself known to BLE clients.

Member Function Documentation

◆ addServiceUUID() [1/2]

bool NimBLEAdvertising::addServiceUUID ( const char * serviceUUID )

Add a service uuid to exposed list of services.

Parameters

[in] serviceUUID The string representation of the service to expose.

Returns: True if the service was added successfully.

◆ addServiceUUID() [2/2]

bool NimBLEAdvertising::addServiceUUID ( const NimBLEUUID & serviceUUID )

Add a service uuid to exposed list of services.

Parameters

[in] serviceUUID The UUID of the service to expose.

Returns: True if the service was added successfully.

◆ addTxPower()

bool NimBLEAdvertising::addTxPower ( )

Add the transmission power level to the advertisement packet.

Returns: True if the transmission power level was added successfully.

◆ enableScanResponse()

void NimBLEAdvertising::enableScanResponse ( bool enable )

Enable scan response data.

Parameters

[in] enable If true, scan response data will be available, false disabled, default = disabled.

The scan response data is sent in response to a scan request from a peer device.

◆ getAdvertisementData()

const NimBLEAdvertisementData & NimBLEAdvertising::getAdvertisementData ( )

Get the current advertisement data.

Returns: a reference to the current advertisement data.

◆ getScanData()

const NimBLEAdvertisementData & NimBLEAdvertising::getScanData ( )

Get the current scan response data.

Returns: a reference to the current scan response data.

◆ isAdvertising()

bool NimBLEAdvertising::isAdvertising ( )

Check if currently advertising.

Returns: True if advertising is active.

◆ refreshAdvertisingData()

bool NimBLEAdvertising::refreshAdvertisingData ( )

Refresh advertsing data dynamically without stop/start cycle. For instance allows refreshing manufacturer data dynamically.

Returns: True if the data was set successfully.

If scan response is enabled it will be refreshed as well.

◆ removeServices()

bool NimBLEAdvertising::removeServices ( )

Remove all service UUIDs from the advertisement.

Returns: True if the services were removed successfully.

◆ removeServiceUUID() [1/2]

bool NimBLEAdvertising::removeServiceUUID ( const char * serviceUUID )

Remove a service UUID from the advertisement.

Parameters

[in] serviceUUID The UUID of the service to remove.

Returns: True if the service was removed successfully.

◆ removeServiceUUID() [2/2]

bool NimBLEAdvertising::removeServiceUUID ( const NimBLEUUID & serviceUUID )

Remove a service UUID from the advertisement.

Parameters

[in] serviceUUID The UUID of the service to remove.

Returns: True if the service was removed successfully.

◆ reset()

bool NimBLEAdvertising::reset ( )

Stops the current advertising and resets the advertising data to the default values.

Returns: True if successful.

◆ setAdvertisementData()

bool NimBLEAdvertising::setAdvertisementData ( const NimBLEAdvertisementData & data )

Set the advertisement data that is to be broadcast in a regular advertisement.

Parameters

[in] data The data to be broadcast.

Returns: True if the data was set successfully.

◆ setAdvertisingCompleteCallback()

void NimBLEAdvertising::setAdvertisingCompleteCallback ( advCompleteCB_t callback )

Set the callback to be invoked when advertising stops.

Parameters

[in] callback The callback to be invoked when advertising stops.

◆ setAdvertisingInterval()

void NimBLEAdvertising::setAdvertisingInterval ( uint16_t interval )

Set the advertising interval.

Parameters

[in] interval The advertising interval in 0.625ms units, 0 = use default.

◆ setAppearance()

bool NimBLEAdvertising::setAppearance ( uint16_t appearance )

Set the device appearance in the advertising data.

Parameters

[in] appearance The appearance of the device in the advertising data. If the appearance value is 0 then the appearance will not be in the advertisement.

Returns: True if the appearance was set successfully.

◆ setConnectableMode()

bool NimBLEAdvertising::setConnectableMode ( uint8_t mode )

Set the type of connectable mode to advertise.

Parameters

[in]

mode

The connectable mode:

BLE_GAP_CONN_MODE_NON (0) - not connectable advertising
BLE_GAP_CONN_MODE_DIR (1) - directed connectable advertising
BLE_GAP_CONN_MODE_UND (2) - undirected connectable advertising

Returns: True if the connectable mode was set, false if the mode is invalid.

◆ setDiscoverableMode()

bool NimBLEAdvertising::setDiscoverableMode ( uint8_t mode )

Set the discoverable mode to use.

Parameters

[in]

mode

The discoverable mode:

BLE_GAP_DISC_MODE_NON (0) - non-discoverable
BLE_GAP_DISC_MODE_LTD (1) - limited discoverable
BLE_GAP_DISC_MODE_GEN (2) - general discoverable

Returns: True if the discoverable mode was set, false if the mode is invalid.

◆ setManufacturerData() [1/3]

bool NimBLEAdvertising::setManufacturerData ( const std::string & data )

Set the advertised manufacturer data.

Parameters

[in] data The data to advertise.

Returns: True if the manufacturer data was set successfully.

◆ setManufacturerData() [2/3]

bool NimBLEAdvertising::setManufacturerData ( const std::vector< uint8_t > & data )

Set the advertised manufacturer data.

Parameters

[in] data The data to advertise.

Returns: True if the manufacturer data was set successfully.

◆ setManufacturerData() [3/3]

bool NimBLEAdvertising::setManufacturerData	(	const uint8_t *	data,
		size_t	length
	)

Set the advertised manufacturer data.

Parameters

[in]	data	The data to advertise.
[in]	length	The length of the data.

Returns: True if the manufacturer data was set successfully.

◆ setMaxInterval()

void NimBLEAdvertising::setMaxInterval ( uint16_t maxInterval )

Set the maximum advertising interval.

Parameters

[in] maxInterval Maximum value for advertising interval in 0.625ms units, 0 = use default.

◆ setMinInterval()

void NimBLEAdvertising::setMinInterval ( uint16_t minInterval )

Set the minimum advertising interval.

Parameters

[in] minInterval Minimum value for advertising interval in 0.625ms units, 0 = use default.

◆ setName()

bool NimBLEAdvertising::setName ( const std::string & name )

Set the advertised name of the device.

Parameters

[in] name The name to advertise.

Returns: True if the name was set successfully.

Note: If the name is too long it will be truncated.

If scan response is enabled the name will be set in the scan response data.

◆ setPreferredParams()

bool NimBLEAdvertising::setPreferredParams	(	uint16_t	minInterval,
		uint16_t	maxInterval
	)

Set the preferred min and max connection intervals to advertise.

Parameters

[in]	minInterval	The minimum preferred connection interval.
[in]	maxInterval	The Maximum preferred connection interval.

Returns: True if the preferred connection interval was set successfully.

Range = 0x0006(7.5ms) to 0x0C80(4000ms), values not within the range will be limited to this range.

◆ setScanFilter()

void NimBLEAdvertising::setScanFilter	(	bool	scanRequestWhitelistOnly,
		bool	connectWhitelistOnly
	)

Set the filtering for the scan filter.

Parameters

[in]	scanRequestWhitelistOnly	If true, only allow scan requests from those on the white list.
[in]	connectWhitelistOnly	If true, only allow connections from those on the white list.

◆ setScanResponseData()

bool NimBLEAdvertising::setScanResponseData ( const NimBLEAdvertisementData & data )

Set the data that is to be provided in a scan response.

Parameters

[in] data The data to be provided in the scan response

Returns: True if the data was set successfully.

The scan response data is sent in response to a scan request from a peer device. If this is set without setting the advertisement data when advertising starts this may be overwritten.

◆ setServiceData() [1/3]

bool NimBLEAdvertising::setServiceData	(	const NimBLEUUID &	uuid,
		const std::string &	data
	)

Set the service data advertised for the UUID.

Parameters

[in]	uuid	The UUID the service data belongs to.
[in]	data	The data to advertise.

Returns: True if the service data was set successfully.

Note: If data length is 0 the service data will not be advertised.

◆ setServiceData() [2/3]

bool NimBLEAdvertising::setServiceData	(	const NimBLEUUID &	uuid,
		const std::vector< uint8_t > &	data
	)

Set the service data advertised for the UUID.

Parameters

[in]	uuid	The UUID the service data belongs to.
[in]	data	The data to advertise.

Returns: True if the service data was set successfully.

Note: If data length is 0 the service data will not be advertised.

◆ setServiceData() [3/3]

bool NimBLEAdvertising::setServiceData	(	const NimBLEUUID &	uuid,
		const uint8_t *	data,
		size_t	length
	)

Set the service data advertised for the UUID.

Parameters

[in]	uuid	The UUID the service data belongs to.
[in]	data	The data to advertise.
[in]	length	The length of the data.

Returns: True if the service data was set successfully.

Note: If data length is 0 the service data will not be advertised.

◆ setURI()

bool NimBLEAdvertising::setURI ( const std::string & uri )

Set the advertised URI.

Parameters

[in] uri The URI to advertise.

Returns: True if the URI was set successfully.

◆ start()

bool NimBLEAdvertising::start	(	uint32_t	duration = `0`,
		const NimBLEAddress *	dirAddr = `nullptr`
	)

Start advertising.

Parameters

[in]	duration	The duration, in milliseconds, to advertise, 0 == advertise forever.
[in]	dirAddr	The address of a peer to directly advertise to.

Returns: True if advertising started successfully.

◆ stop()

bool NimBLEAdvertising::stop ( )

Stop advertising.

Returns: True if advertising stopped successfully.

Public Member Functions

Detailed Description

Member Function Documentation

◆ addServiceUUID() [1/2]

◆ addServiceUUID() [2/2]

◆ addTxPower()

◆ enableScanResponse()

◆ getAdvertisementData()

◆ getScanData()

◆ isAdvertising()

◆ refreshAdvertisingData()

◆ removeServices()

◆ removeServiceUUID() [1/2]

◆ removeServiceUUID() [2/2]

◆ reset()

◆ setAdvertisementData()

◆ setAdvertisingCompleteCallback()

◆ setAdvertisingInterval()

◆ setAppearance()

◆ setConnectableMode()

◆ setDiscoverableMode()

◆ setManufacturerData() [1/3]

◆ setManufacturerData() [2/3]

◆ setManufacturerData() [3/3]

◆ setMaxInterval()

◆ setMinInterval()

◆ setName()

◆ setPreferredParams()

◆ setScanFilter()

◆ setScanResponseData()

◆ setServiceData() [1/3]

◆ setServiceData() [2/3]

◆ setServiceData() [3/3]

◆ setURI()

◆ start()

◆ stop()