Mistake on this page?
Report an issue in GitHub or email us
Data Structures | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes
Gap Class Referenceabstract
Ble » Gap

#include <Gap.h>

Data Structures

struct  AdvertisementCallbackParams_t
 
struct  CentralPrivacyConfiguration_t
 
struct  ConnectionCallbackParams_t
 
struct  ConnectionParams_t
 
struct  DisconnectionCallbackParams_t
 
struct  GapState_t
 
struct  PeripheralPrivacyConfiguration_t
 
struct  Whitelist_t
 

Public Types

enum  DeprecatedAddressType_t { ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC, ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC, ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE, ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE }
 
enum  TimeoutSource_t { TIMEOUT_SRC_ADVERTISING = 0x00, TIMEOUT_SRC_SECURITY_REQUEST = 0x01, TIMEOUT_SRC_SCAN = 0x02, TIMEOUT_SRC_CONN = 0x03 }
 
enum  DisconnectionReason_t {
  AUTHENTICATION_FAILURE = 0x05, CONNECTION_TIMEOUT = 0x08, REMOTE_USER_TERMINATED_CONNECTION = 0x13, REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14,
  REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, LOCAL_HOST_TERMINATED_CONNECTION = 0x16, CONN_INTERVAL_UNACCEPTABLE = 0x3B
}
 
enum  AdvertisingPolicyMode_t { ADV_POLICY_IGNORE_WHITELIST = 0, ADV_POLICY_FILTER_SCAN_REQS = 1, ADV_POLICY_FILTER_CONN_REQS = 2, ADV_POLICY_FILTER_ALL_REQS = 3 }
 
enum  ScanningPolicyMode_t { SCAN_POLICY_IGNORE_WHITELIST = 0, SCAN_POLICY_FILTER_ALL_ADV = 1 }
 
enum  InitiatorPolicyMode_t { INIT_POLICY_IGNORE_WHITELIST = 0, INIT_POLICY_FILTER_ALL_ADV = 1 }
 
enum  Role_t { PERIPHERAL = 0x1, CENTRAL = 0x2 }
 
typedef BLEProtocol::AddressType_t AddressType_t
 
typedef BLEProtocol::AddressType_t addr_type_t
 
typedef BLEProtocol::AddressBytes_t Address_t
 
typedef BLEProtocol::AddressBytes_t address_t
 
typedef ble::connection_handle_t Handle_t
 
typedef ble::random_address_type_t RandomAddressType_t
 
typedef ble::peer_address_type_t PeerAddressType_t
 
typedef FunctionPointerWithContext< const AdvertisementCallbackParams_t * > AdvertisementReportCallback_t
 
typedef FunctionPointerWithContext< TimeoutSource_tTimeoutEventCallback_t
 
typedef CallChainOfFunctionPointersWithContext< TimeoutSource_tTimeoutEventCallbackChain_t
 
typedef FunctionPointerWithContext< const ConnectionCallbackParams_t * > ConnectionEventCallback_t
 
typedef CallChainOfFunctionPointersWithContext< const ConnectionCallbackParams_t * > ConnectionEventCallbackChain_t
 
typedef FunctionPointerWithContext< const DisconnectionCallbackParams_t * > DisconnectionEventCallback_t
 
typedef CallChainOfFunctionPointersWithContext< const DisconnectionCallbackParams_t * > DisconnectionEventCallbackChain_t
 
typedef FunctionPointerWithContext< bool > RadioNotificationEventCallback_t
 
typedef FunctionPointerWithContext< const Gap * > GapShutdownCallback_t
 
typedef CallChainOfFunctionPointersWithContext< const Gap * > GapShutdownCallbackChain_t
 

Public Member Functions

virtual ble_error_t setAddress (BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address)
 
virtual ble_error_t getAddress (BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address)
 
virtual uint16_t getMinAdvertisingInterval (void) const
 
virtual uint16_t getMinNonConnectableAdvertisingInterval (void) const
 
virtual uint16_t getMaxAdvertisingInterval (void) const
 
virtual ble_error_t stopAdvertising (void)
 
virtual ble_error_t stopScan ()
 
virtual ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, PeerAddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
 
virtual ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
 
ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, DeprecatedAddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
 
virtual ble_error_t disconnect (Handle_t connectionHandle, DisconnectionReason_t reason)
 
virtual ble_error_t disconnect (DisconnectionReason_t reason)
 
virtual ble_error_t getPreferredConnectionParams (ConnectionParams_t *params)
 
virtual ble_error_t setPreferredConnectionParams (const ConnectionParams_t *params)
 
virtual ble_error_t updateConnectionParams (Handle_t handle, const ConnectionParams_t *params)
 
virtual ble_error_t setDeviceName (const uint8_t *deviceName)
 
virtual ble_error_t getDeviceName (uint8_t *deviceName, unsigned *lengthP)
 
virtual ble_error_t setAppearance (GapAdvertisingData::Appearance appearance)
 
virtual ble_error_t getAppearance (GapAdvertisingData::Appearance *appearanceP)
 
virtual ble_error_t setTxPower (int8_t txPower)
 
virtual void getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP)
 
virtual uint8_t getMaxWhitelistSize (void) const
 
virtual ble_error_t getWhitelist (Whitelist_t &whitelist) const
 
virtual ble_error_t setWhitelist (const Whitelist_t &whitelist)
 
virtual ble_error_t setAdvertisingPolicyMode (AdvertisingPolicyMode_t mode)
 
virtual ble_error_t setScanningPolicyMode (ScanningPolicyMode_t mode)
 
virtual ble_error_t setInitiatorPolicyMode (InitiatorPolicyMode_t mode)
 
virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode (void) const
 
virtual ScanningPolicyMode_t getScanningPolicyMode (void) const
 
virtual InitiatorPolicyMode_t getInitiatorPolicyMode (void) const
 
GapState_t getState (void) const
 
void setAdvertisingType (GapAdvertisingParams::AdvertisingType_t advType)
 
void setAdvertisingInterval (uint16_t interval)
 
void setAdvertisingTimeout (uint16_t timeout)
 
ble_error_t startAdvertising (void)
 
void clearAdvertisingPayload (void)
 
ble_error_t accumulateAdvertisingPayload (uint8_t flags)
 
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::Appearance app)
 
ble_error_t accumulateAdvertisingPayloadTxPower (int8_t power)
 
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 
ble_error_t updateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 
ble_error_t setAdvertisingPayload (const GapAdvertisingData &payload)
 
const GapAdvertisingDatagetAdvertisingPayload (void) const
 
ble_error_t accumulateScanResponse (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 
void clearScanResponse (void)
 
ble_error_t setScanParams (uint16_t interval=GapScanningParams::SCAN_INTERVAL_MAX, uint16_t window=GapScanningParams::SCAN_WINDOW_MAX, uint16_t timeout=0, bool activeScanning=false)
 
ble_error_t setScanParams (const GapScanningParams &scanningParams)
 
ble_error_t setScanInterval (uint16_t interval)
 
ble_error_t setScanWindow (uint16_t window)
 
ble_error_t setScanTimeout (uint16_t timeout)
 
ble_error_t setActiveScanning (bool activeScanning)
 
ble_error_t startScan (void(*callback)(const AdvertisementCallbackParams_t *params))
 
template<typename T >
ble_error_t startScan (T *object, void(T::*callbackMember)(const AdvertisementCallbackParams_t *params))
 
virtual ble_error_t initRadioNotification (void)
 
virtual ble_error_t enablePrivacy (bool enable)
 
virtual ble_error_t setPeripheralPrivacyConfiguration (const PeripheralPrivacyConfiguration_t *configuration)
 
virtual ble_error_t getPeripheralPrivacyConfiguration (PeripheralPrivacyConfiguration_t *configuration)
 
virtual ble_error_t setCentralPrivacyConfiguration (const CentralPrivacyConfiguration_t *configuration)
 
virtual ble_error_t getCentralPrivacyConfiguration (CentralPrivacyConfiguration_t *configuration)
 
GapAdvertisingParamsgetAdvertisingParams (void)
 
const GapAdvertisingParamsgetAdvertisingParams (void) const
 
void setAdvertisingParams (const GapAdvertisingParams &newParams)
 
void onTimeout (TimeoutEventCallback_t callback)
 
TimeoutEventCallbackChain_tonTimeout ()
 
void onConnection (ConnectionEventCallback_t callback)
 
template<typename T >
void onConnection (T *tptr, void(T::*mptr)(const ConnectionCallbackParams_t *))
 
ConnectionEventCallbackChain_tonConnection ()
 
void onDisconnection (DisconnectionEventCallback_t callback)
 
template<typename T >
void onDisconnection (T *tptr, void(T::*mptr)(const DisconnectionCallbackParams_t *))
 
DisconnectionEventCallbackChain_tonDisconnection ()
 
void onRadioNotification (void(*callback)(bool param))
 
template<typename T >
void onRadioNotification (T *tptr, void(T::*mptr)(bool))
 
void onShutdown (const GapShutdownCallback_t &callback)
 
template<typename T >
void onShutdown (T *objPtr, void(T::*memberPtr)(const Gap *))
 
GapShutdownCallbackChain_tonShutdown ()
 
virtual ble_error_t reset (void)
 
void processConnectionEvent (Handle_t handle, Role_t role, PeerAddressType_t peerAddrType, const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t ownAddrType, const BLEProtocol::AddressBytes_t ownAddr, const ConnectionParams_t *connectionParams, const uint8_t *peerResolvableAddr=NULL, const uint8_t *localResolvableAddr=NULL)
 
void processConnectionEvent (Handle_t handle, Role_t role, BLEProtocol::AddressType_t peerAddrType, const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t ownAddrType, const BLEProtocol::AddressBytes_t ownAddr, const ConnectionParams_t *connectionParams, const uint8_t *peerResolvableAddr=NULL, const uint8_t *localResolvableAddr=NULL)
 
void processDisconnectionEvent (Handle_t handle, DisconnectionReason_t reason)
 
void processAdvertisementReport (const BLEProtocol::AddressBytes_t peerAddr, int8_t rssi, bool isScanResponse, GapAdvertisingParams::AdvertisingType_t type, uint8_t advertisingDataLen, const uint8_t *advertisingData, PeerAddressType_t addressType)
 
void processAdvertisementReport (const BLEProtocol::AddressBytes_t peerAddr, int8_t rssi, bool isScanResponse, GapAdvertisingParams::AdvertisingType_t type, uint8_t advertisingDataLen, const uint8_t *advertisingData, BLEProtocol::AddressType_t addressType=BLEProtocol::AddressType::RANDOM_STATIC)
 
void processTimeoutEvent (TimeoutSource_t source)
 

Static Public Member Functions

static uint16_t MSEC_TO_GAP_DURATION_UNITS (uint32_t durationInMillis)
 
static ble_error_t getRandomAddressType (const BLEProtocol::AddressBytes_t address, RandomAddressType_t *addressType)
 

Static Public Attributes

static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN
 
static const uint16_t UNIT_1_25_MS = 1250
 
static const PeripheralPrivacyConfiguration_t default_peripheral_privacy_configuration
 
static const CentralPrivacyConfiguration_t default_central_privacy_configuration
 

Protected Member Functions

virtual ble_error_t startRadioScan (const GapScanningParams &scanningParams)
 
 Gap ()
 

Protected Attributes

GapAdvertisingParams _advParams
 
GapAdvertisingData _advPayload
 
GapScanningParams _scanningParams
 
GapAdvertisingData _scanResponse
 
uint8_t connectionCount
 
GapState_t state
 
bool scanningActive
 
TimeoutEventCallbackChain_t timeoutCallbackChain
 
RadioNotificationEventCallback_t radioNotificationCallback
 
AdvertisementReportCallback_t onAdvertisementReport
 
ConnectionEventCallbackChain_t connectionCallChain
 
DisconnectionEventCallbackChain_t disconnectionCallChain
 

Detailed Description

Define device discovery, connection and link management procedures.

Accessing gap

Instance of a Gap class for a given BLE device should be accessed using BLE::gap(). The reference returned remains valid until the BLE instance shut down (see BLE::shutdown()).

// assuming ble_device has been initialized
BLE& ble_device;
Gap& gap = ble_device.gap();
Advertising

Advertising consists of broadcasting at a regular interval a small amount of data containing valuable informations about the device. These packets may be scanned by peer devices listening on BLE advertising channels.

Scanners may also request additional information from a device advertising by sending a scan request. If the broadcaster accepts scan requests, it can reply with a scan response packet containing additional information.

// assuming gap has been initialized
Gap& gap;
// construct the packet to advertise
GapAdvertisingData advertising_data;
// Add advertiser flags
advertising_data.addFlags(
);
// Add the name of the device to the advertising data
static const uint8_t device_name[] = "HRM";
advertising_data.addData(
device_name,
sizeof(device_name)
);
// set the advertising data in the gap instance, they will be used when
// advertising starts.
gap.setAdvertisingPayload(advertising_data);
// Configure the advertising procedure
GapAdvertisingParams advertising_params(
0 // The advertising procedure will not timeout
);
gap.setAdvertisingParams(advertising_params);
// start the advertising procedure, the device will advertise its flag and the
// name "HRM". Other peers will also be allowed to connect to it.
Privacy

Privacy is a feature that allows a device to avoid being tracked by other (untrusted) devices. The device achieves it by periodically generating a new random address. The random address may be a resolvable random address, enabling trusted devices to recognise it as belonging to the same device. These trusted devices receive an Identity Resolution Key (IRK) during pairing. This is handled by the SecurityManager and relies on the other device accepting and storing the IRK.

Privacy needs to be enabled by calling enablePrivacy() after having initialised the SecurityManager since privacy requires SecurityManager to handle IRKs. The behaviour of privacy enabled devices is set by using setCentralPrivacyConfiguration() which specifies what the device should be with devices using random addresses. Random addresses generated by privacy enabled device can be of two types: resolvable (by devices who have the IRK) and unresolvable. Unresolvable addresses can't be used for connecting and connectable advertising therefore a resolvable one will be used for these regardless of the privacy configuration.

Scanning

Scanning consist of listening for peer advertising packets. From a scan, a device can identify devices available in its environment.

If the device scans actively, then it will send scan request to scannable advertisers and collect their scan response.

// assuming gap has been initialized
Gap& gap;
// Handle advertising packet by dumping their content
void handle_advertising_packet(const AdvertisementCallbackParams_t* packet)
{
printf("Packet received: \r\n");
printf(" - peer address: %02X:%02X:%02X:%02X:%02X:%02X\r\n",
packet->peerAddr[5], packet->peerAddr[4], packet->peerAddr[3],
packet->peerAddr[2], packet->peerAddr[1], packet->peerAddr[0]);
printf(" - rssi: %d", packet->rssi);
printf(" - scan response: %s\r\n", packet->isScanresponse ? "true" : "false");
printf(" - advertising type: %d\r\n", packet->type);
printf(" - advertising type: %d\r\n", packet->type);
printf(" - Advertising data: \r\n");
// parse advertising data, it is a succession of AD structures where
// the first byte is the size of the AD structure, the second byte the
// type of the data and remaining bytes are the value.
for (size_t i = 0; i < packet->advertisingDataLen; i += packet->advertisingData[i]) {
printf(" - type: 0X%02X, data: ", packet->advertisingData[i + 1]);
for (size_t j = 0; j < packet->advertisingData[i] - 2; ++j) {
printf("0X%02X ", packet->advertisingData[i + 2 + j]);
}
printf("\r\n");
}
}
// set the scan parameters
100, // interval between two scan window in ms
50, // scan window: period during which the device listen for advertising packets.
0, // the scan process never ends
true // the device sends scan request to scannable peers.
);
// start the scan procedure
gap.startScan(handle_advertising_packet);
Connection event handling

A peer may connect device advertising connectable packets. The advertising procedure ends as soon as the device is connected.

A device accepting a connection request from a peer is named a peripheral, and the device initiating the connection is named a central.

Peripheral and central receive a connection event when the connection is effective.

Gap& gap;
// handle connection event
void when_connected(const ConnectionCallbackParams_t *connection_event) {
// If this callback is entered, then the connection to a peer is effective.
}
// register connection event handler, which will be invoked whether the device
// acts as a central or a peripheral
gap.onConnection(when_connected);
Connection initiation

Connection is initiated central devices.

// assuming gap has been initialized
Gap& gap;
// Handle the connection event
void handle_connection(const ConnectionCallbackParams_t* connection_event)
{
// event handling
}
// Handle advertising packet: connect to the first connectable device
void handle_advertising_packet(const AdvertisementCallbackParams_t* packet)
{
return;
}
// register connection event handler
gap.onConnection(handle_connection);
Gap::ConnectionParams_t connection_parameters = {
50, // min connection interval
100, // max connection interval
0, // slave latency
600 // connection supervision timeout
};
// scan parameter used to find the device to connect to
GapScanningParams scanning_params(
100, // interval
100, // window
0, // timeout
false // active
);
// Initiate the connection procedure
gap.connect(
packet->peerAddr,
packet->addressType,
&connection_parameters,
&scanning_params
);
}
// set the scan parameters
100, // interval between two scan window in ms
50, // scan window: period during which the device listen for advertising packets.
0, // the scan process never ends
true // the device sends scan request to scannable peers.
);
// start the scan procedure
gap.startScan(handle_advertising_packet);
disconnection

The application code initiates a disconnection when it calls the disconnect(Handle_t, DisconnectionReason_t) function.

Disconnection may also be initiated by the remote peer or the local controller/stack. To catch all disconnection events, application code may set up an handler taking care of disconnection events by calling onDisconnection().

Member Typedef Documentation

Address-type for BLEProtocol addresses.

Deprecated:
Use BLEProtocol::AddressType_t instead.

48-bit address, LSB format.

Deprecated:
Use BLEProtocol::AddressBytes_t instead.

48-bit address, LSB format.

Deprecated:
Use BLEProtocol::AddressBytes_t instead.

Address-type for BLEProtocol addresses.

Deprecated:
Use BLEProtocol::AddressType_t instead.

Type of the callback handling scanned advertisement packets.

See also
Gap::startScan().

Connection event handler.

See also
Gap::onConnection().

Callchain of connection event handlers.

See also
Gap::onConnection().

Disconnection event handler.

See also
Gap::onDisconnection().

Callchain of disconnection event handlers.

See also
Gap::onDisconnection().

Gap shutdown event handler.

See also
Gap::onShutdown().

Callchain of gap shutdown event handler.

See also
Gap::onShutdown().

Opaque value type representing a connection handle.

It is used to identify to refer to a specific connection across Gap, GattClient and GattEvent API.

Note
instances are generated by in the connection callback.

Enumeration of peer address types

Radio notification event handler.

See also
Gap::onRadioNotification().

Enumeration of random address types.

Timeout event handler.

See also
Gap::onTimeout().

Callchain of timeout event handlers.

See also
Gap::onTimeout().

Member Enumeration Documentation

Advertising policy filter modes.

See also
Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.2.
Enumerator
ADV_POLICY_IGNORE_WHITELIST 

The whitelist is not used to filter peer request during advertising.

ADV_POLICY_FILTER_SCAN_REQS 

The whitelist is used to filter peer scan requests.

ADV_POLICY_FILTER_CONN_REQS 

The whitelist is used to filter peer connection requests.

ADV_POLICY_FILTER_ALL_REQS 

The whitelist is used to filter peer scan and connection requests.

Address-type for BLEProtocol addresses.

Deprecated:
Use BLEProtocol::AddressType_t instead. The following constants have been left in their deprecated state to transparently support existing applications that may have used Gap::ADDR_TYPE_*.

Enumeration of disconnection reasons.

Attention
There might be a mismatch between the disconnection reason passed to disconnect() and the disconnection event generated locally because the disconnection reason passed to disconnect() is the disconnection reason to be transmitted to the peer.
Enumerator
AUTHENTICATION_FAILURE 

GAP or GATT failed to authenticate the peer.

CONNECTION_TIMEOUT 

The connection timed out.

Attention
shall not be used as a reason in disconnect().
REMOTE_USER_TERMINATED_CONNECTION 

Connection terminated by the user.

REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES 

Remote device terminated connection due to low resources.

REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF 

Remote device terminated connection due to power off.

LOCAL_HOST_TERMINATED_CONNECTION 

Indicate that the local user or the internal Bluetooth subsystem terminated the connection.

Attention
shall not be used as a reason in disconnect().
CONN_INTERVAL_UNACCEPTABLE 

Connection parameters were unacceptable.

Connection initiation policy filter mode.

See also
Bluetooth Core Specification 4.2 (vol. 6), Part B, Section 4.4.4.
Enumerator
INIT_POLICY_IGNORE_WHITELIST 

Connection can be initiated to any device.

INIT_POLICY_FILTER_ALL_ADV 

Connection initiation is restricted to the devices present in the whitelist.

Enumeration of GAP roles.

Note
The BLE API does not express the broadcaster and scanner roles.
Attention
A device can fulfill different roles concurrently.
Enumerator
PERIPHERAL 

Peripheral Role.

The device can advertise and it can be connected by a central. It acts as a slave when connected.

Note
A peripheral is a broadcaster.
CENTRAL 

Central Role.

The device can scan and initiate connection to peripherals. It acts as the master when a connection is established.

Note
A central is a scanner.

Scanning policy filter mode.

See also
Bluetooth Core Specification 4.2 (Vol. 6), Part B, Section 4.3.3.
Enumerator
SCAN_POLICY_IGNORE_WHITELIST 

The whitelist is not used for scanning operations.

SCAN_POLICY_FILTER_ALL_ADV 

The whitelist is used to filter incoming advertising.

Enumeration of possible timeout sources.

Enumerator
TIMEOUT_SRC_ADVERTISING 

Advertising timeout.

TIMEOUT_SRC_SECURITY_REQUEST 

Security request timeout.

TIMEOUT_SRC_SCAN 

Scanning timeout.

TIMEOUT_SRC_CONN 

Connection timeout.

Constructor & Destructor Documentation

Gap::Gap ( )
inlineprotected

Construct a Gap instance.

Member Function Documentation

ble_error_t Gap::accumulateAdvertisingPayload ( uint8_t  flags)
inline

Set gap flags in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addFlags(flags);
gap.setAdvertisingPayload(payload);
Parameters
[in]flagsThe flags to be added.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
ble_error_t Gap::accumulateAdvertisingPayload ( GapAdvertisingData::Appearance  app)
inline

Set the appearance field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addAppearance(app);
gap.setAdvertisingPayload(payload);
Parameters
[in]appThe appearance to advertise.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
ble_error_t Gap::accumulateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)
inline

Add a new field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addData(type, data, len);
gap.setAdvertisingPayload(payload);
Parameters
[in]typeIdentity of the field being added.
[in]dataBuffer containing the value of the field.
[in]lenLength of the data buffer.
Returns
BLE_ERROR_NONE if the advertisement payload was updated based on matching AD type; otherwise, an appropriate error.
Note
When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS, COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS, COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS, COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the supplied value is appended to the values previously added to the payload.
ble_error_t Gap::accumulateAdvertisingPayloadTxPower ( int8_t  power)
inline

Set the Tx Power field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.addTxPower(power);
gap.setAdvertisingPayload(payload);
Parameters
[in]powerTransmit power in dBm used by the controller to advertise.
Returns
BLE_ERROR_NONE if the data was successfully added to the advertising payload.
ble_error_t Gap::accumulateScanResponse ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)
inline

Add a new field in the advertising payload.

Parameters
[in]typeAD type identifier.
[in]databuffer containing AD data.
[in]lenLength of the data buffer.
Returns
BLE_ERROR_NONE if the data was successfully added to the scan response payload.
void Gap::clearAdvertisingPayload ( void  )
inline

Reset the value of the advertising payload advertised.

void Gap::clearScanResponse ( void  )
inline

Reset the content of the scan response.

Note
This should be followed by a call to Gap::setAdvertisingPayload() or Gap::startAdvertising() before the update takes effect.
virtual ble_error_t Gap::connect ( const BLEProtocol::AddressBytes_t  peerAddr,
PeerAddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
)
inlinevirtual

Initiate a connection to a peer.

Once the connection is established, a ConnectionCallbackParams_t event is emitted to handlers that have been registered with onConnection().

Parameters
[in]peerAddrMAC address of the peer. It must be in LSB format.
[in]peerAddrTypeAddress type of the peer. It is usually obtained from advertising frames.
[in]connectionParamsConnection parameters to use.
[in]scanParamsScan parameters used to find the peer.
Returns
BLE_ERROR_NONE if connection establishment procedure is started successfully. The connectionCallChain (if set) is invoked upon a connection event.
virtual ble_error_t Gap::connect ( const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
)
inlinevirtual

Initiate a connection to a peer.

Once the connection is established, a ConnectionCallbackParams_t event is emitted to handlers that have been registered with onConnection().

Parameters
[in]peerAddrMAC address of the peer. It must be in LSB format.
[in]peerAddrTypeAddress type of the peer.
[in]connectionParamsConnection parameters to use.
[in]scanParamsScan parameters used to find the peer.
Deprecated:
BLEProtocol::AddressType_t is not able to to carry accurate meaning when privacy is in use. Please Uses the connect overload that accept a PeerAddressType_t as the peer address type.
Returns
BLE_ERROR_NONE if connection establishment procedure is started successfully. The connectionCallChain (if set) is invoked upon a connection event.
ble_error_t Gap::connect ( const BLEProtocol::AddressBytes_t  peerAddr,
DeprecatedAddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
)

Initiate a connection to a peer.

See also
connect()
Deprecated:
This funtion overloads Gap::connect( const BLEProtocol::Address_t peerAddr, BLEProtocol::AddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams ) to maintain backward compatibility for changes from Gap::AddressType_t to BLEProtocol::AddressType_t.
virtual ble_error_t Gap::disconnect ( Handle_t  connectionHandle,
DisconnectionReason_t  reason 
)
inlinevirtual

Initiate a disconnection procedure.

Once the disconnection procedure has completed a DisconnectionCallbackParams_t, the event is emitted to handlers that have been registered with onDisconnection().

Parameters
[in]reasonReason of the disconnection transmitted to the peer.
[in]connectionHandleHandle of the connection to end.
Returns
BLE_ERROR_NONE if the disconnection procedure successfully started.
virtual ble_error_t Gap::disconnect ( DisconnectionReason_t  reason)
inlinevirtual

Initiate a disconnection procedure.

Deprecated:
This version of disconnect() doesn't take a connection handle. It works reliably only for stacks that are limited to a single connection. Use Gap::disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) instead.
Parameters
[in]reasonThe reason for disconnection; to be sent back to the peer.
Returns
BLE_ERROR_NONE if disconnection was successful.
virtual ble_error_t Gap::enablePrivacy ( bool  enable)
inlinevirtual

Enable or disable privacy mode of the local device.

When privacy is enabled, the system use private addresses while it scans, advertises or initiate a connection. The device private address is renewed every 15 minutes.

Configuration

The privacy feature can be configured with the help of the functions setPeripheralPrivacyConfiguration and setCentralPrivacyConfiguration which respectively set the privacy configuration of the peripheral and central role.

Default configuration of peripheral role

By default private resolvable addresses are used for all procedures; including advertisement of non connectable packets. Connection request from an unknown initiator with a private resolvable address triggers the pairing procedure.

Default configuration of central role

By default private resolvable addresses are used for all procedures; including active scanning. Addresses present in advertisement packet are resolved and advertisement packets are forwarded to the application even if the advertiser private address is unknown.

Parameters
[in]enableShould be set to true to enable the privacy mode and false to disable it.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
virtual ble_error_t Gap::getAddress ( BLEProtocol::AddressType_t typeP,
BLEProtocol::AddressBytes_t  address 
)
inlinevirtual

Fetch the current address and its type.

Parameters
[out]typePType of the current address set.
[out]addressValue of the current address.
Note
If privacy is enabled the device address may be unavailable to application code.
Returns
BLE_ERROR_NONE on success.
GapAdvertisingParams& Gap::getAdvertisingParams ( void  )
inline

Get the current advertising parameters.

Returns
A reference to the current advertising parameters.
const GapAdvertisingParams& Gap::getAdvertisingParams ( void  ) const
inline

Const alternative to Gap::getAdvertisingParams().

Returns
A const reference to the current advertising parameters.
const GapAdvertisingData& Gap::getAdvertisingPayload ( void  ) const
inline

Get a reference to the current advertising payload.

Returns
A reference to the current advertising payload.
virtual AdvertisingPolicyMode_t Gap::getAdvertisingPolicyMode ( void  ) const
inlinevirtual

Get the current advertising policy filter mode.

Returns
The current advertising policy filter mode.
virtual ble_error_t Gap::getAppearance ( GapAdvertisingData::Appearance appearanceP)
inlinevirtual

Get the value of the appearance characteristic in the GAP service.

Parameters
[out]appearancePThe current device-appearance value.
Returns
BLE_ERROR_NONE if the device-appearance was fetched correctly from the underlying BLE stack.
virtual ble_error_t Gap::getCentralPrivacyConfiguration ( CentralPrivacyConfiguration_t configuration)
inlinevirtual

Get the privacy configuration used by the central role.

Parameters
[out]configurationThe variable filled with the current configuration.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
virtual ble_error_t Gap::getDeviceName ( uint8_t *  deviceName,
unsigned *  lengthP 
)
inlinevirtual

Get the value of the device name characteristic in the Generic Access Service.

To obtain the length of the deviceName value, this function is invoked with the deviceName parameter set to NULL.

Parameters
[out]deviceNamePointer to an empty buffer where the UTF-8 non NULL-terminated string is placed.
[in,out]lengthPLength of the deviceName buffer. If the device name is successfully copied, then the length of the device name string (excluding the null terminator) replaces this value.
Returns
BLE_ERROR_NONE if the device name was fetched correctly from the underlying BLE stack.
Note
If the device name is longer than the size of the supplied buffer, length returns the complete device name length and not the number of bytes actually returned in deviceName. The application may use this information to retry with a suitable buffer size.
virtual InitiatorPolicyMode_t Gap::getInitiatorPolicyMode ( void  ) const
inlinevirtual

Get the current initiator policy filter mode.

Returns
The current scan policy filter mode.
virtual uint16_t Gap::getMaxAdvertisingInterval ( void  ) const
inlinevirtual

Get the maximum advertising interval in milliseconds.

Returns
Maximum Advertising interval in milliseconds.
virtual uint8_t Gap::getMaxWhitelistSize ( void  ) const
inlinevirtual

Get the maximum size of the whitelist.

Returns
Maximum size of the whitelist.
Note
If using Mbed OS, you can configure the size of the whitelist by setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta config file.
virtual uint16_t Gap::getMinAdvertisingInterval ( void  ) const
inlinevirtual

Get the minimum advertising interval in milliseconds, which can be used for connectable advertising types.

Returns
Minimum Advertising interval in milliseconds for connectable undirected and connectable directed advertising types.
virtual uint16_t Gap::getMinNonConnectableAdvertisingInterval ( void  ) const
inlinevirtual

Get the minimum advertising interval in milliseconds, which can be used for nonconnectable advertising type.

Returns
Minimum Advertising interval in milliseconds for scannable undirected and nonconnectable undirected event types.
virtual ble_error_t Gap::getPeripheralPrivacyConfiguration ( PeripheralPrivacyConfiguration_t configuration)
inlinevirtual

Get the privacy configuration used by the peripheral role.

Parameters
[out]configurationThe variable filled with the current configuration.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
virtual void Gap::getPermittedTxPowerValues ( const int8_t **  valueArrayPP,
size_t *  countP 
)
inlinevirtual

Query the underlying stack for allowed Tx power values.

Parameters
[out]valueArrayPPReceive the immutable array of Tx values.
[out]countPReceive the array's size.
virtual ble_error_t Gap::getPreferredConnectionParams ( ConnectionParams_t params)
inlinevirtual

Returned the preferred connection parameters exposed in the GATT Generic Access Service.

Parameters
[out]paramsStructure where the parameters are stored.
Returns
BLE_ERROR_NONE if the parameters were successfully filled into params.
ble_error_t Gap::getRandomAddressType ( const BLEProtocol::AddressBytes_t  address,
RandomAddressType_t addressType 
)
static

Return the type of a random address.

Parameters
[in]addressThe random address to retrieve the type from. The address must be ordered in little endian.
[out]addressTypeType of the address to fill.
Returns
BLE_ERROR_NONE in case of success or BLE_ERROR_INVALID_PARAM if the address in input was not identifiable as a random address.
virtual ScanningPolicyMode_t Gap::getScanningPolicyMode ( void  ) const
inlinevirtual

Get the current scan policy filter mode.

Returns
The current scan policy filter mode.
GapState_t Gap::getState ( void  ) const
inline

Get the current advertising and connection states of the device.

Returns
The current GAP state of the device.
virtual ble_error_t Gap::getWhitelist ( Whitelist_t whitelist) const
inlinevirtual

Get the Link Layer to use the internal whitelist when scanning, advertising or initiating a connection depending on the filter policies.

Parameters
[in,out]whitelistDefine the whitelist instance which is used to store the whitelist requested. In input, the caller provisions memory.
Returns
BLE_ERROR_NONE if the implementation's whitelist was successfully copied into the supplied reference.
virtual ble_error_t Gap::initRadioNotification ( void  )
inlinevirtual

Enable radio-notification events.

Radio Notification is a feature that notifies the application when the radio is in use.

The ACTIVE signal is sent before the radio event starts. The nACTIVE signal is sent at the end of the radio event. The application programmer can use these signals to synchronize application logic with radio activity. For example, the ACTIVE signal can be used to shut off external devices, to manage peak current drawn during periods when the radio is on or to trigger sensor data collection for transmission in the Radio Event.

Returns
BLE_ERROR_NONE on successful initialization, otherwise an error code.
static uint16_t Gap::MSEC_TO_GAP_DURATION_UNITS ( uint32_t  durationInMillis)
inlinestatic

Convert milliseconds into 1.25ms units.

This function may be used to convert ms time of connection intervals into the format expected for connection parameters.

Parameters
[in]durationInMillisThe duration in milliseconds.
Returns
The duration in unit of 1.25ms.
void Gap::onConnection ( ConnectionEventCallback_t  callback)
inline

Register a callback handling connection events.

Parameters
[in]callbackEvent handler being registered.
Note
A callback may be unregistered using onConnection().detach(callback).
template<typename T >
void Gap::onConnection ( T *  tptr,
void(T::*)(const ConnectionCallbackParams_t *)  mptr 
)
inline

Register a callback handling connection events.

Parameters
[in]tptrInstance used to invoke mptr.
[in]mptrEvent handler being registered.
Note
A callback may be unregistered using onConnection().detach(callback).
ConnectionEventCallbackChain_t& Gap::onConnection ( )
inline

Get the callchain of registered connection event handlers.

Note
To register callbacks, use onConnection().add(callback).
To unregister callbacks, use onConnection().detach(callback).
Returns
A reference to the connection event callbacks chain.
void Gap::onDisconnection ( DisconnectionEventCallback_t  callback)
inline

Register a callback handling disconnection events.

Parameters
[in]callbackEvent handler being registered.
Note
A callback may be unregistered using onDisconnection().detach(callback).
template<typename T >
void Gap::onDisconnection ( T *  tptr,
void(T::*)(const DisconnectionCallbackParams_t *)  mptr 
)
inline

Register a callback handling disconnection events.

Parameters
[in]tptrInstance used to invoke mptr.
[in]mptrEvent handler being registered.
Note
A callback may be unregistered using onDisconnection().detach(callback).
DisconnectionEventCallbackChain_t& Gap::onDisconnection ( )
inline

Get the callchain of registered disconnection event handlers.

Note
To register callbacks use onDisconnection().add(callback).
To unregister callbacks use onDisconnection().detach(callback).
Returns
A reference to the disconnection event callbacks chain.
void Gap::onRadioNotification ( void(*)(bool param)  callback)
inline

Set the radio-notification events handler.

Radio Notification is a feature that enables ACTIVE and INACTIVE (nACTIVE) signals from the stack that notify the application when the radio is in use.

The ACTIVE signal is sent before the radio event starts. The nACTIVE signal is sent at the end of the radio event. The application programmer can use these signals to synchronize application logic with radio activity. For example, the ACTIVE signal can be used to shut off external devices, to manage peak current drawn during periods when the radio is on or to trigger sensor data collection for transmission in the Radio Event.

Parameters
[in]callbackApplication handler to be invoked in response to a radio ACTIVE/INACTIVE event.
template<typename T >
void Gap::onRadioNotification ( T *  tptr,
void(T::*)(bool)  mptr 
)
inline

Set the radio-notification events handler.

Parameters
[in]tptrInstance to be used to invoke mptr.
[in]mptrApplication handler to be invoked in response to a radio ACTIVE/INACTIVE event.
void Gap::onShutdown ( const GapShutdownCallback_t callback)
inline

Register a Gap shutdown event handler.

The handler is called when the Gap instance is about to shut down. It is usually issued after a call to BLE::shutdown().

Parameters
[in]callbackShutdown event handler to register.
Note
To unregister a shutdown event handler, use onShutdown().detach(callback).
template<typename T >
void Gap::onShutdown ( T *  objPtr,
void(T::*)(const Gap *)  memberPtr 
)
inline

Register a Gap shutdown event handler.

Parameters
[in]objPtrInstance used to invoke memberPtr.
[in]memberPtrShutdown event handler to register.
GapShutdownCallbackChain_t& Gap::onShutdown ( )
inline

Access the callchain of shutdown event handler.

Note
To register callbacks, use onShutdown().add(callback).
To unregister callbacks, use onShutdown().detach(callback).
Returns
A reference to the shutdown event callback chain.
void Gap::onTimeout ( TimeoutEventCallback_t  callback)
inline

Register a callback handling timeout events.

Parameters
[in]callbackEvent handler being registered.
Note
A callback may be unregistered using onTimeout().detach(callback).
See also
TimeoutSource_t
TimeoutEventCallbackChain_t& Gap::onTimeout ( )
inline

Get the callchain of registered timeout event handlers.

Note
To register callbacks, use onTimeout().add(callback).
To unregister callbacks, use onTimeout().detach(callback).
Returns
A reference to the timeout event callbacks chain.
void Gap::processAdvertisementReport ( const BLEProtocol::AddressBytes_t  peerAddr,
int8_t  rssi,
bool  isScanResponse,
GapAdvertisingParams::AdvertisingType_t  type,
uint8_t  advertisingDataLen,
const uint8_t *  advertisingData,
PeerAddressType_t  addressType 
)

Forward a received advertising packet to all registered event handlers listening for scanned packet events.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]peerAddrAddress of the peer that has emitted the packet.
[in]rssiValue of the RSSI measured for the received packet.
[in]isScanResponseIf true, then the packet is a response to a scan request.
[in]typeAdvertising type of the packet.
[in]advertisingDataLenLength of the advertisement data received.
[in]advertisingDataPointer to the advertisement packet's data.
[in]addressTypeType of the address of the peer that has emitted the packet.
void Gap::processAdvertisementReport ( const BLEProtocol::AddressBytes_t  peerAddr,
int8_t  rssi,
bool  isScanResponse,
GapAdvertisingParams::AdvertisingType_t  type,
uint8_t  advertisingDataLen,
const uint8_t *  advertisingData,
BLEProtocol::AddressType_t  addressType = BLEProtocol::AddressType::RANDOM_STATIC 
)

Forward a received advertising packet to all registered event handlers listening for scanned packet events.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]peerAddrAddress of the peer that has emitted the packet.
[in]rssiValue of the RSSI measured for the received packet.
[in]isScanResponseIf true, then the packet is a response to a scan request.
[in]typeAdvertising type of the packet.
[in]advertisingDataLenLength of the advertisement data received.
[in]advertisingDataPointer to the advertisement packet's data.
[in]addressTypeType of the address of the peer that has emitted the packet.
Deprecated:
The type BLEProtocol::AddressType_t is not suitable when privacy is enabled. Use the overload that accepts a PeerAddressType_t instead.
void Gap::processConnectionEvent ( Handle_t  handle,
Role_t  role,
PeerAddressType_t  peerAddrType,
const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  ownAddrType,
const BLEProtocol::AddressBytes_t  ownAddr,
const ConnectionParams_t connectionParams,
const uint8_t *  peerResolvableAddr = NULL,
const uint8_t *  localResolvableAddr = NULL 
)

Notify all registered connection event handlers of a connection event.

Attention
This function is meant to be called from the BLE stack specific implementation when a connection event occurs.
Parameters
[in]handleHandle of the new connection.
[in]roleRole of this BLE device in the connection.
[in]peerAddrTypeAddress type of the connected peer.
[in]peerAddrAddress of the connected peer.
[in]ownAddrTypeAddress type this device uses for this connection.
[in]ownAddrAddress this device uses for this connection. This parameter may be NULL if the local address is not available.
[in]connectionParamsParameters of the connection.
[in]peerResolvableAddrResolvable address used by the peer.
[in]localResolvableAddrresolvable address used by the local device.
void Gap::processConnectionEvent ( Handle_t  handle,
Role_t  role,
BLEProtocol::AddressType_t  peerAddrType,
const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  ownAddrType,
const BLEProtocol::AddressBytes_t  ownAddr,
const ConnectionParams_t connectionParams,
const uint8_t *  peerResolvableAddr = NULL,
const uint8_t *  localResolvableAddr = NULL 
)

Notify all registered connection event handlers of a connection event.

Attention
This function is meant to be called from the BLE stack specific implementation when a connection event occurs.
Parameters
[in]handleHandle of the new connection.
[in]roleRole of this BLE device in the connection.
[in]peerAddrTypeAddress type of the connected peer.
[in]peerAddrAddress of the connected peer.
[in]ownAddrTypeAddress type this device uses for this connection.
[in]ownAddrAddress this device uses for this connection.
[in]connectionParamsParameters of the connection.
[in]peerResolvableAddrResolvable address used by the peer.
[in]localResolvableAddrresolvable address used by the local device.
Deprecated:
The type BLEProtocol::AddressType_t is not suitable when privacy is enabled. Use the overload that accepts a PeerAddressType_t instead.
void Gap::processDisconnectionEvent ( Handle_t  handle,
DisconnectionReason_t  reason 
)
inline

Notify all registered disconnection event handlers of a disconnection event.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]handleHandle of the terminated connection.
[in]reasonReason of the disconnection.
void Gap::processTimeoutEvent ( TimeoutSource_t  source)
inline

Notify the occurrence of a timeout event to all registered timeout events handler.

Attention
This function is meant to be called from the BLE stack specific implementation when a disconnection event occurs.
Parameters
[in]sourceSource of the timout event.
virtual ble_error_t Gap::reset ( void  )
inlinevirtual

Reset the Gap instance.

Reset process starts by notifying all registered shutdown event handlers that the Gap instance is about to be shut down. Then, it clears all Gap state of the associated object and then cleans the state present in the vendor implementation.

This function is meant to be overridden in the platform-specific subclass. Nevertheless, the subclass only resets its state and not the data held in Gap members. This is achieved by a call to Gap::reset() from the subclass' reset() implementation.

Returns
BLE_ERROR_NONE on success.
Note
Currently, a call to reset() does not reset the advertising and scan parameters to default values.
ble_error_t Gap::setActiveScanning ( bool  activeScanning)
inline

Enable or disable active scanning.

Parameters
[in]activeScanningIf set to true, then the scanner sends scan requests to a scannable or connectable advertiser. If set to false then the scanner does not send any request during the scan procedure.
Returns
BLE_ERROR_NONE if active scanning was successfully set.
Note
If scanning is already in progress, then active scanning is enabled for the underlying BLE stack.
virtual ble_error_t Gap::setAddress ( BLEProtocol::AddressType_t  type,
const BLEProtocol::AddressBytes_t  address 
)
inlinevirtual

Set the device MAC address and type.

The address set is used in subsequent GAP operations: scanning, advertising and connection initiation.

Parameters
[in]typeType of the address to set.
[in]addressValue of the address to set. It is ordered in little endian. This parameter is not considered if the address type is RANDOM_PRIVATE_RESOLVABLE or RANDOM_PRIVATE_NON_RESOLVABLE. For those types of address, the BLE API itself generates the address.
Note
Some implementation may refuse to set a new PUBLIC address.
Random static address set does not change.
Deprecated:
Starting with mbed-os-5.9.0 this function is deprecated and address management is delegated to implementation. Implementations may or may not continue to support this function. Compliance with the Bluetooth specification and unification of behaviour between implementations are the key reasons behind this change:
  • Many implementations do not allow changing of the public address. Therefore programs relying on this function are not portable across BLE implementations.
  • The Bluetooth specification forbid replacement of the random static address; this address can be set once and only once: at startup. Depending on the underlying implementation the random address may or may not have been set automatically at startup; therefore update of the Random Static address after ble initialisation may be a fault. As a result calls to this function were not portable. Furthermore replacement of the random static address silently invalidates the bond stored in the secure database.
Returns
BLE_ERROR_NONE on success.
void Gap::setAdvertisingInterval ( uint16_t  interval)
inline

Set the advertising interval.

Parameters
[in]intervalAdvertising interval in units of milliseconds. Advertising is disabled if interval is 0. If interval is smaller than the minimum supported value, then the minimum supported value is used instead. This minimum value can be discovered using getMinAdvertisingInterval().

This field must be set to 0 if connectionMode is equal to ADV_CONNECTABLE_DIRECTED.

Note
Decreasing this value allows central devices to detect a peripheral faster, at the expense of the radio using more power due to the higher data transmit rate.
void Gap::setAdvertisingParams ( const GapAdvertisingParams newParams)
inline

Set the advertising parameters.

Parameters
[in]newParamsThe new advertising parameters.
ble_error_t Gap::setAdvertisingPayload ( const GapAdvertisingData payload)
inline

Set the value of the payload advertised.

Parameters
[in]payloadA reference to a user constructed advertisement payload to set.
Returns
BLE_ERROR_NONE if the advertisement payload was successfully set.
virtual ble_error_t Gap::setAdvertisingPolicyMode ( AdvertisingPolicyMode_t  mode)
inlinevirtual

Set the advertising policy filter mode to be used during the next advertising procedure.

Parameters
[in]modeNew advertising policy filter mode.
Returns
BLE_ERROR_NONE if the specified policy filter mode was set successfully.
void Gap::setAdvertisingTimeout ( uint16_t  timeout)
inline

Set the advertising duration.

A timeout event is genenerated once the advertising period expired.

Parameters
[in]timeoutAdvertising timeout (in seconds) between 0x1 and 0x3FFF. The special value 0 may be used to disable the advertising timeout.
void Gap::setAdvertisingType ( GapAdvertisingParams::AdvertisingType_t  advType)
inline

Set the advertising type to use during the advertising procedure.

Parameters
[in]advTypeNew type of advertising to use.
virtual ble_error_t Gap::setAppearance ( GapAdvertisingData::Appearance  appearance)
inlinevirtual

Set the value of the appearance characteristic in the GAP service.

Parameters
[in]appearanceThe new value for the device-appearance.
Returns
BLE_ERROR_NONE if the new appearance was set correctly.
virtual ble_error_t Gap::setCentralPrivacyConfiguration ( const CentralPrivacyConfiguration_t configuration)
inlinevirtual

Set the privacy configuration used by the central role.

Parameters
[in]configurationThe configuration to set.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
virtual ble_error_t Gap::setDeviceName ( const uint8_t *  deviceName)
inlinevirtual

Set the value of the device name characteristic in the Generic Access Service.

Parameters
[in]deviceNameThe new value for the device-name. This is a UTF-8 encoded, NULL-terminated string.
Returns
BLE_ERROR_NONE if the device name was set correctly.
virtual ble_error_t Gap::setInitiatorPolicyMode ( InitiatorPolicyMode_t  mode)
inlinevirtual

Set the initiator policy filter mode to be used during the next connection initiation.

Parameters
[in]modeNew initiator policy filter mode.
Returns
BLE_ERROR_NONE if the specified policy filter mode was set successfully.
virtual ble_error_t Gap::setPeripheralPrivacyConfiguration ( const PeripheralPrivacyConfiguration_t configuration)
inlinevirtual

Set the privacy configuration used by the peripheral role.

Parameters
[in]configurationThe configuration to set.
Returns
BLE_ERROR_NONE in case of success or an appropriate error code.
virtual ble_error_t Gap::setPreferredConnectionParams ( const ConnectionParams_t params)
inlinevirtual

Set the value of the preferred connection parameters exposed in the GATT Generic Access Service.

A connected peer may read the characteristic exposing these parameters and request an update of the connection parameters to accomodate the local device.

Parameters
[in]paramsValue of the preferred connection parameters.
Returns
BLE_ERROR_NONE if the preferred connection params were set correctly.
ble_error_t Gap::setScanInterval ( uint16_t  interval)
inline

Set the interval parameter used during scanning procedures.

Parameters
[in]intervalInterval in ms between the start of two consecutive scan windows. That value is greater or equal to the scan window value. The maximum allowed value is 10.24ms.
Returns
BLE_ERROR_NONE if the scan interval was correctly set.
virtual ble_error_t Gap::setScanningPolicyMode ( ScanningPolicyMode_t  mode)
inlinevirtual

Set the scan policy filter mode to be used during the next scan procedure.

Parameters
[in]modeNew scan policy filter mode.
Returns
BLE_ERROR_NONE if the specified policy filter mode was set successfully.
ble_error_t Gap::setScanParams ( uint16_t  interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t  window = GapScanningParams::SCAN_WINDOW_MAX,
uint16_t  timeout = 0,
bool  activeScanning = false 
)
inline

Set the parameters used during a scan procedure.

Parameters
[in]intervalin ms between the start of two consecutive scan windows. That value is greater or equal to the scan window value. The maximum allowed value is 10.24ms.
[in]windowPeriod in ms during which the scanner listens to advertising channels. That value is in the range 2.5ms to 10.24s.
[in]timeoutDuration in seconds of the scan procedure if any. The special value 0 disable specific duration of the scan procedure.
[in]activeScanningIf set to true, then the scanner sends scan requests to a scannable or connectable advertiser. If set to false, then the scanner does not send any request during the scan procedure.
Returns
BLE_ERROR_NONE if the scan parameters were correctly set.
Note
The scanning window divided by the interval determines the duty cycle for scanning. For example, if the interval is 100ms and the window is 10ms, then the controller scans for 10 percent of the time.
If the interval and the window are set to the same value, then the device scans continuously during the scan procedure. The scanning frequency changes at every interval.
Once the scanning parameters have been configured, scanning can be enabled by using startScan().
The scan interval and window are recommendations to the BLE stack.
ble_error_t Gap::setScanParams ( const GapScanningParams scanningParams)
inline

Set the parameters used during a scan procedure.

Parameters
[in]scanningParamsParameter struct containing the interval, period, timeout and active scanning toggle.
Returns
BLE_ERROR_NONE if the scan parameters were correctly set.
Note
All restrictions from setScanParams(uint16_t, uint16_t, uint16_t, bool) apply.
ble_error_t Gap::setScanTimeout ( uint16_t  timeout)
inline

Set the timeout parameter used during scanning procedures.

Parameters
[in]timeoutDuration in seconds of the scan procedure if any. The special value 0 disables specific duration of the scan procedure.
Returns
BLE_ERROR_NONE if the scan timeout was correctly set.
Note
If scanning is already active, the updated value of scanTimeout is propagated to the underlying BLE stack.
ble_error_t Gap::setScanWindow ( uint16_t  window)
inline

Set the window parameter used during scanning procedures.

Parameters
[in]windowPeriod in ms during which the scanner listens to advertising channels. That value is in the range 2.5ms to 10.24s.
Returns
BLE_ERROR_NONE if the scan window was correctly set.
Note
If scanning is already active, the updated value of scanWindow is propagated to the underlying BLE stack.
virtual ble_error_t Gap::setTxPower ( int8_t  txPower)
inlinevirtual

Set the radio's transmit power.

Parameters
[in]txPowerRadio's transmit power in dBm.
Returns
BLE_ERROR_NONE if the new radio's transmit power was set correctly.
virtual ble_error_t Gap::setWhitelist ( const Whitelist_t whitelist)
inlinevirtual

Set the value of the whitelist to be used during GAP procedures.

Parameters
[in]whitelistA reference to a whitelist containing the addresses to be copied to the internal whitelist.
Returns
BLE_ERROR_NONE if the implementation's whitelist was successfully populated with the addresses in the given whitelist.
Note
The whitelist must not contain addresses of type BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE. This results in a BLE_ERROR_INVALID_PARAM because the remote peer might change its private address at any time, and it is not possible to resolve it.
If the input whitelist is larger than getMaxWhitelistSize(), then BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
ble_error_t Gap::startAdvertising ( void  )
inline

Start the advertising procedure.

Returns
BLE_ERROR_NONE if the device started advertising successfully.
virtual ble_error_t Gap::startRadioScan ( const GapScanningParams scanningParams)
inlineprotectedvirtual

Start scanning procedure in the underlying BLE stack.

Parameters
[in]scanningParamsParameters of the scan procedure.
Returns
BLE_ERROR_NONE if the scan procedure was successfully started.
ble_error_t Gap::startScan ( void(*)(const AdvertisementCallbackParams_t *params)  callback)
inline

Start the scanning procedure.

Packets received during the scan procedure are forwarded to the scan packet handler passed as argument to this function.

Parameters
[in]callbackAdvertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback.
Returns
BLE_ERROR_NONE if the device successfully started the scan procedure.
Note
The parameters used by the procedure are defined by setScanParams().
template<typename T >
ble_error_t Gap::startScan ( T *  object,
void(T::*)(const AdvertisementCallbackParams_t *params)  callbackMember 
)
inline

Start the scanning procedure.

Packets received during the scan procedure are forwarded to the scan packet handler passed as argument to this function.

Parameters
[in]objectInstance used to invoke callbackMember.
[in]callbackMemberAdvertisement packet event handler. Upon reception of an advertising packet, the packet is forwarded to callback invoked from object.
Returns
BLE_ERROR_NONE if the device successfully started the scan procedure.
Note
The parameters used by the procedure are defined by setScanParams().
virtual ble_error_t Gap::stopAdvertising ( void  )
inlinevirtual

Stop the ongoing advertising procedure.

Note
The current advertising parameters remain in effect.
Return values
BLE_ERROR_NONEif the advertising procedure has been successfully stopped.
virtual ble_error_t Gap::stopScan ( void  )
inlinevirtual

Stop the ongoing scanning procedure.

The current scanning parameters remain in effect.

Return values
BLE_ERROR_NONEif successfully stopped scanning procedure.
ble_error_t Gap::updateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
)
inline

Update a particular field in the advertising payload.

A call to this function is equivalent to:

Gap &gap;
payload.updateData(type, data, len);
gap.setAdvertisingPayload(payload);
Parameters
[in]typeId of the field to update.
[in]datadata buffer containing the new value of the field.
[in]lenLength of the data buffer.
Note
If advertisements are enabled, then the update takes effect immediately.
Returns
BLE_ERROR_NONE if the advertisement payload was updated based on matching AD type; otherwise, an appropriate error.
virtual ble_error_t Gap::updateConnectionParams ( Handle_t  handle,
const ConnectionParams_t params 
)
inlinevirtual

Update connection parameters of an existing connection.

In the central role, this initiates a Link Layer connection parameter update procedure. In the peripheral role, this sends the corresponding L2CAP request and waits for the central to perform the procedure.

Parameters
[in]handleConnection Handle.
[in]paramsPointer to desired connection parameters.
Returns
BLE_ERROR_NONE if the connection parameters were updated correctly.

Field Documentation

GapAdvertisingParams Gap::_advParams
protected

Current advertising parameters.

GapAdvertisingData Gap::_advPayload
protected

Current advertising data.

GapScanningParams Gap::_scanningParams
protected

Current scanning parameters.

GapAdvertisingData Gap::_scanResponse
protected

Current scan response.

const unsigned Gap::ADDR_LEN = BLEProtocol::ADDR_LEN
static

Length (in octets) of the BLE MAC address.

ConnectionEventCallbackChain_t Gap::connectionCallChain
protected

Callchain containing all registered callback handlers for connection events.

uint8_t Gap::connectionCount
protected

Number of open connections.

const Gap::CentralPrivacyConfiguration_t Gap::default_central_privacy_configuration
static
const Gap::PeripheralPrivacyConfiguration_t Gap::default_peripheral_privacy_configuration
static
DisconnectionEventCallbackChain_t Gap::disconnectionCallChain
protected

Callchain containing all registered callback handlers for disconnection events.

AdvertisementReportCallback_t Gap::onAdvertisementReport
protected

The registered callback handler for scanned advertisement packet notifications.

RadioNotificationEventCallback_t Gap::radioNotificationCallback
protected

The registered callback handler for radio notification events.

bool Gap::scanningActive
protected

Active scanning flag.

GapState_t Gap::state
protected

Current GAP state.

TimeoutEventCallbackChain_t Gap::timeoutCallbackChain
protected

Callchain containing all registered callback handlers for timeout events.

const uint16_t Gap::UNIT_1_25_MS = 1250
static

Number of microseconds in 1.25 milliseconds.


The documentation for this class was generated from the following files:
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.