BA / Mbed OS BaBoRo_test2
Embed: (wiki syntax)

« Back to documentation index

GenericGap Class Reference

Generic implementation of the Gap class. More...

#include <GenericGap.h>

Inherits Gap, and ble::pal::ConnectionEventMonitor.

Public Types

enum  DeprecatedAddressType_t
 

Address-type for BLEProtocol addresses.

More...
enum  TimeoutSource_t { TIMEOUT_SRC_ADVERTISING = 0x00, TIMEOUT_SRC_SECURITY_REQUEST = 0x01, TIMEOUT_SRC_SCAN = 0x02, TIMEOUT_SRC_CONN = 0x03 }
 

Enumeration of possible timeout sources.

More...
enum  DisconnectionReason_t {
  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
}
 

Enumeration of disconnection reasons.

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

Advertising policy filter modes.

More...
enum  ScanningPolicyMode_t { SCAN_POLICY_IGNORE_WHITELIST = 0, SCAN_POLICY_FILTER_ALL_ADV = 1 }
 

Scanning policy filter mode.

More...
enum  InitiatorPolicyMode_t { INIT_POLICY_IGNORE_WHITELIST = 0, INIT_POLICY_FILTER_ALL_ADV = 1 }
 

Connection initiation policy filter mode.

More...
enum  Role_t { PERIPHERAL = 0x1, CENTRAL = 0x2 }
 

Enumeration of GAP roles.

More...
typedef BLEProtocol::AddressType_t AddressType_t
 Address-type for BLEProtocol addresses.
typedef BLEProtocol::AddressType_t addr_type_t
 Address-type for BLEProtocol addresses.
typedef BLEProtocol::AddressBytes_t Address_t
 48-bit address, LSB format.
typedef BLEProtocol::AddressBytes_t address_t
 48-bit address, LSB format.
typedef ble::connection_handle_t Handle_t
 Opaque value type representing a connection handle.
typedef
FunctionPointerWithContext
< const
AdvertisementCallbackParams_t * > 
AdvertisementReportCallback_t
 Type of the callback handling scanned advertisement packets.
typedef
FunctionPointerWithContext
< TimeoutSource_t
TimeoutEventCallback_t
 Timeout event handler.
typedef
CallChainOfFunctionPointersWithContext
< TimeoutSource_t
TimeoutEventCallbackChain_t
 Callchain of timeout event handlers.
typedef
FunctionPointerWithContext
< const
ConnectionCallbackParams_t * > 
ConnectionEventCallback_t
 Connection event handler.
typedef
CallChainOfFunctionPointersWithContext
< const
ConnectionCallbackParams_t * > 
ConnectionEventCallbackChain_t
 Callchain of connection event handlers.
typedef
FunctionPointerWithContext
< const
DisconnectionCallbackParams_t * > 
DisconnectionEventCallback_t
 Disconnection event handler.
typedef
CallChainOfFunctionPointersWithContext
< const
DisconnectionCallbackParams_t * > 
DisconnectionEventCallbackChain_t
 Callchain of disconnection event handlers.
typedef
FunctionPointerWithContext
< bool > 
RadioNotificationEventCallback_t
 Radio notification event handler.
typedef
FunctionPointerWithContext
< const Gap * > 
GapShutdownCallback_t
 Gap shutdown event handler.
typedef
CallChainOfFunctionPointersWithContext
< const Gap * > 
GapShutdownCallbackChain_t
 Callchain of gap shutdown event handler.

Public Member Functions

 GenericGap (pal::EventQueue &event_queue, pal::Gap &pal_gap, pal::GenericAccessService &generic_access_service)
 Construct a GenericGap instance for a given BLE instance ID.
virtual ~GenericGap ()
virtual ble_error_t setAddress (BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address)
virtual ble_error_t getAddress (BLEProtocol::AddressType_t *type, BLEProtocol::AddressBytes_t address)
virtual uint16_t getMinAdvertisingInterval () const
virtual uint16_t getMinNonConnectableAdvertisingInterval () const
virtual uint16_t getMaxAdvertisingInterval () const
virtual ble_error_t stopAdvertising ()
virtual ble_error_t stopScan ()
virtual ble_error_t connect (const BLEProtocol::AddressBytes_t peerAddr, BLEProtocol::AddressType_t peerAddrType, const ConnectionParams_t *connectionParams, const GapScanningParams *scanParams)
virtual ble_error_t disconnect (Handle_t connectionHandle, DisconnectionReason_t reason)
virtual ble_error_t updateConnectionParams (Handle_t handle, const ConnectionParams_t *params)
virtual ble_error_t getPreferredConnectionParams (ConnectionParams_t *params)
virtual ble_error_t setPreferredConnectionParams (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
virtual ble_error_t startRadioScan (const GapScanningParams &scanningParams)
virtual ble_error_t initRadioNotification (void)
virtual ble_error_t setAdvertisingData (const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse)
virtual ble_error_t startAdvertising (const GapAdvertisingParams &params)
virtual ble_error_t reset (void)
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)
void processDisconnectionEvent (Handle_t handle, DisconnectionReason_t reason)
 MBED_DEPRECATED ("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") ble_error_t connect(const BLEProtocol
 Initiate a connection to a peer.
 MBED_DEPRECATED ("Use disconnect(Handle_t, DisconnectionReason_t) instead.") virtual ble_error_t disconnect(DisconnectionReason_t reason)
 Initiate a disconnection procedure.
GapState_t getState (void) const
 Get the current advertising and connection states of the device.
void setAdvertisingType (GapAdvertisingParams::AdvertisingType_t advType)
 Set the advertising type to use during the advertising procedure.
void setAdvertisingInterval (uint16_t interval)
 Set the advertising interval.
void setAdvertisingTimeout (uint16_t timeout)
 Set the advertising duration.
ble_error_t startAdvertising (void)
 Start the advertising procedure.
void clearAdvertisingPayload (void)
 Reset the value of the advertising payload advertised.
ble_error_t accumulateAdvertisingPayload (uint8_t flags)
 Set gap flags in the advertising payload.
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::Appearance app)
 Set the appearance field in the advertising payload.
ble_error_t accumulateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Add a new field in the advertising payload.
ble_error_t accumulateAdvertisingPayloadTxPower (int8_t power)
 Set the Tx Power field in the advertising payload.
ble_error_t updateAdvertisingPayload (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Update a particular field in the advertising payload.
ble_error_t setAdvertisingPayload (const GapAdvertisingData &payload)
 Set the value of the payload advertised.
const GapAdvertisingDatagetAdvertisingPayload (void) const
 Get a reference to the current advertising payload.
ble_error_t accumulateScanResponse (GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len)
 Add a new field in the advertising payload.
void clearScanResponse (void)
 Reset the content of the scan response.
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)
 Set the parameters used during a scan procedure.
ble_error_t setScanInterval (uint16_t interval)
 Set the interval parameter used during scanning procedures.
ble_error_t setScanWindow (uint16_t window)
 Set the window parameter used during scanning procedures.
ble_error_t setScanTimeout (uint16_t timeout)
 Set the timeout parameter used during scanning procedures.
ble_error_t setActiveScanning (bool activeScanning)
 Enable or disable active scanning.
ble_error_t startScan (void(*callback)(const AdvertisementCallbackParams_t *params))
 Start the scanning procedure.
template<typename T >
ble_error_t startScan (T *object, void(T::*callbackMember)(const AdvertisementCallbackParams_t *params))
 Start the scanning procedure.
GapAdvertisingParamsgetAdvertisingParams (void)
 Get the current advertising parameters.
const GapAdvertisingParamsgetAdvertisingParams (void) const
 Const alternative to Gap::getAdvertisingParams().
void setAdvertisingParams (const GapAdvertisingParams &newParams)
 Set the advertising parameters.
void onTimeout (TimeoutEventCallback_t callback)
 Register a callback handling timeout events.
TimeoutEventCallbackChain_tonTimeout ()
 Get the callchain of registered timeout event handlers.
void onConnection (ConnectionEventCallback_t callback)
 Register a callback handling connection events.
template<typename T >
void onConnection (T *tptr, void(T::*mptr)(const ConnectionCallbackParams_t *))
 Register a callback handling connection events.
ConnectionEventCallbackChain_tonConnection ()
 Get the callchain of registered connection event handlers.
void onDisconnection (DisconnectionEventCallback_t callback)
 Register a callback handling disconnection events.
template<typename T >
void onDisconnection (T *tptr, void(T::*mptr)(const DisconnectionCallbackParams_t *))
 Register a callback handling disconnection events.
DisconnectionEventCallbackChain_tonDisconnection ()
 Get the callchain of registered disconnection event handlers.
void onRadioNotification (void(*callback)(bool param))
 Set the radio-notification events handler.
template<typename T >
void onRadioNotification (T *tptr, void(T::*mptr)(bool))
 Set the radio-notification events handler.
void onShutdown (const GapShutdownCallback_t &callback)
 Register a Gap shutdown event handler.
template<typename T >
void onShutdown (T *objPtr, void(T::*memberPtr)(const Gap *))
 Register a Gap shutdown event handler.
GapShutdownCallbackChain_tonShutdown ()
 Access the callchain of shutdown event handler.
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)
 Forward a received advertising packet to all registered event handlers listening for scanned packet events.
void processTimeoutEvent (TimeoutSource_t source)
 Notify the occurrence of a timeout event to all registered timeout events handler.

Static Public Member Functions

static uint16_t MSEC_TO_GAP_DURATION_UNITS (uint32_t durationInMillis)
 Convert milliseconds into 1.25ms units.

Static Public Attributes

static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN
 Length (in octets) of the BLE MAC address.
static const uint16_t UNIT_1_25_MS = 1250
 Number of microseconds in 1.25 milliseconds.

Protected Attributes

GapAdvertisingParams _advParams
 Current advertising parameters.
GapAdvertisingData _advPayload
 Current advertising data.
GapScanningParams _scanningParams
 Current scanning parameters.
GapAdvertisingData _scanResponse
 Current scan response.
uint8_t connectionCount
 Number of open connections.
GapState_t state
 Current GAP state.
bool scanningActive
 Active scanning flag.
TimeoutEventCallbackChain_t timeoutCallbackChain
 Callchain containing all registered callback handlers for timeout events.
RadioNotificationEventCallback_t radioNotificationCallback
 The registered callback handler for radio notification events.
AdvertisementReportCallback_t onAdvertisementReport
 The registered callback handler for scanned advertisement packet notifications.
ConnectionEventCallbackChain_t connectionCallChain
 Callchain containing all registered callback handlers for connection events.
DisconnectionEventCallbackChain_t disconnectionCallChain
 Callchain containing all registered callback handlers for disconnection events.

Detailed Description

Generic implementation of the Gap class.

It requires a pal::Gap and a pal::GenericAccessService injected at construction site.

Attention:
: Not part of the public interface of BLE API.

Definition at line 44 of file GenericGap.h.


Member Typedef Documentation

Address-type for BLEProtocol addresses.

Definition at line 286 of file Gap.h.

48-bit address, LSB format.

Definition at line 319 of file Gap.h.

48-bit address, LSB format.

Definition at line 312 of file Gap.h.

Address-type for BLEProtocol addresses.

Definition at line 279 of file Gap.h.

Type of the callback handling scanned advertisement packets.

See also:
Gap::startScan().

Definition at line 624 of file Gap.h.

Connection event handler.

See also:
Gap::onConnection().

Definition at line 780 of file Gap.h.

Callchain of connection event handlers.

See also:
Gap::onConnection().

Definition at line 788 of file Gap.h.

Disconnection event handler.

See also:
Gap::onDisconnection().

Definition at line 796 of file Gap.h.

Callchain of disconnection event handlers.

See also:
Gap::onDisconnection().

Definition at line 804 of file Gap.h.

Gap shutdown event handler.

See also:
Gap::onShutdown().

Definition at line 818 of file Gap.h.

Callchain of gap shutdown event handler.

See also:
Gap::onShutdown().

Definition at line 826 of file Gap.h.

typedef ble::connection_handle_t Handle_t [inherited]

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.

Definition at line 497 of file Gap.h.

Radio notification event handler.

See also:
Gap::onRadioNotification().

Definition at line 811 of file Gap.h.

Timeout event handler.

See also:
Gap::onTimeout().

Definition at line 764 of file Gap.h.

Callchain of timeout event handlers.

See also:
Gap::onTimeout().

Definition at line 772 of file Gap.h.


Member Enumeration Documentation

enum AdvertisingPolicyMode_t [inherited]

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.

Definition at line 397 of file Gap.h.

enum DeprecatedAddressType_t [inherited]

Address-type for BLEProtocol addresses.

Definition at line 295 of file Gap.h.

enum DisconnectionReason_t [inherited]

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

Definition at line 355 of file Gap.h.

enum InitiatorPolicyMode_t [inherited]

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.

Definition at line 441 of file Gap.h.

enum Role_t [inherited]

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.

Definition at line 553 of file Gap.h.

enum ScanningPolicyMode_t [inherited]

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.

Definition at line 424 of file Gap.h.

enum TimeoutSource_t [inherited]

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.

Definition at line 325 of file Gap.h.


Constructor & Destructor Documentation

GenericGap ( pal::EventQueue event_queue,
pal::Gap pal_gap,
pal::GenericAccessService generic_access_service 
)

Construct a GenericGap instance for a given BLE instance ID.

Parameters:
ble_instance_idId of the BLE instance using this instance.
pal_gapGAP Platform abstraction instance containing the base GAP primitives.
generic_access_servicePlatform abstraction instance managing the GATT generic access service.

Definition at line 379 of file GenericGap.cpp.

~GenericGap (  ) [virtual]
See also:
Gap::~Gap

Definition at line 400 of file GenericGap.cpp.


Member Function Documentation

ble_error_t accumulateAdvertisingPayload ( uint8_t  flags ) [inherited]

Set gap flags in the advertising payload.

A call to this function is equivalent to:

 Gap &gap;

 GapAdvertisingData payload = gap.getAdvertisingPayload();
 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.

Definition at line 1501 of file Gap.h.

ble_error_t accumulateAdvertisingPayload ( GapAdvertisingData::Appearance  app ) [inherited]

Set the appearance field in the advertising payload.

A call to this function is equivalent to:

 Gap &gap;

 GapAdvertisingData payload = gap.getAdvertisingPayload();
 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.

Definition at line 1535 of file Gap.h.

ble_error_t accumulateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
) [inherited]

Add a new field in the advertising payload.

A call to this function is equivalent to:

 Gap &gap;

 GapAdvertisingData payload = gap.getAdvertisingPayload();
 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.

Definition at line 1611 of file Gap.h.

ble_error_t accumulateAdvertisingPayloadTxPower ( int8_t  power ) [inherited]

Set the Tx Power field in the advertising payload.

A call to this function is equivalent to:

 Gap &gap;

 GapAdvertisingData payload = gap.getAdvertisingPayload();
 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.

Definition at line 1569 of file Gap.h.

ble_error_t accumulateScanResponse ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
) [inherited]

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.

Definition at line 1708 of file Gap.h.

void clearAdvertisingPayload ( void   ) [inherited]

Reset the value of the advertising payload advertised.

Definition at line 1477 of file Gap.h.

void clearScanResponse ( void   ) [inherited]

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.

Definition at line 1731 of file Gap.h.

ble_error_t connect ( const BLEProtocol::AddressBytes_t  peerAddr,
BLEProtocol::AddressType_t  peerAddrType,
const ConnectionParams_t connectionParams,
const GapScanningParams scanParams 
) [virtual]
See also:
Gap::connect

Reimplemented from Gap.

Definition at line 498 of file GenericGap.cpp.

ble_error_t disconnect ( Handle_t  connectionHandle,
DisconnectionReason_t  reason 
) [virtual]
See also:
Gap::disconnect

Reimplemented from Gap.

Definition at line 541 of file GenericGap.cpp.

ble_error_t getAddress ( BLEProtocol::AddressType_t type,
BLEProtocol::AddressBytes_t  address 
) [virtual]
See also:
Gap::getAddress

Reimplemented from Gap.

Definition at line 445 of file GenericGap.cpp.

GapAdvertisingParams& getAdvertisingParams ( void   ) [inherited]

Get the current advertising parameters.

Returns:
A reference to the current advertising parameters.

Definition at line 1992 of file Gap.h.

const GapAdvertisingParams& getAdvertisingParams ( void   ) const [inherited]

Const alternative to Gap::getAdvertisingParams().

Returns:
A const reference to the current advertising parameters.

Definition at line 2002 of file Gap.h.

const GapAdvertisingData& getAdvertisingPayload ( void   ) const [inherited]

Get a reference to the current advertising payload.

Returns:
A reference to the current advertising payload.

Definition at line 1693 of file Gap.h.

Gap::AdvertisingPolicyMode_t getAdvertisingPolicyMode ( void   ) const [virtual]
See also:
Gap::getAdvertisingPolicyMode

Reimplemented from Gap.

Definition at line 793 of file GenericGap.cpp.

ble_error_t getAppearance ( GapAdvertisingData::Appearance appearanceP ) [virtual]
See also:
Gap::getAppearance

Reimplemented from Gap.

Definition at line 628 of file GenericGap.cpp.

ble_error_t getDeviceName ( uint8_t *  deviceName,
unsigned *  lengthP 
) [virtual]
See also:
Gap::getDeviceName

Reimplemented from Gap.

Definition at line 596 of file GenericGap.cpp.

Gap::InitiatorPolicyMode_t getInitiatorPolicyMode ( void   ) const [virtual]
See also:
Gap::getInitiatorPolicyMode

Reimplemented from Gap.

Definition at line 803 of file GenericGap.cpp.

uint16_t getMaxAdvertisingInterval ( void   ) const [virtual]
See also:
Gap::getMaxAdvertisingInterval

Reimplemented from Gap.

Definition at line 471 of file GenericGap.cpp.

uint8_t getMaxWhitelistSize ( void   ) const [virtual]
See also:
Gap::getMaxWhitelistSize

Reimplemented from Gap.

Definition at line 648 of file GenericGap.cpp.

uint16_t getMinAdvertisingInterval ( void   ) const [virtual]
See also:
Gap::getMinAdvertisingInterval

Reimplemented from Gap.

Definition at line 461 of file GenericGap.cpp.

uint16_t getMinNonConnectableAdvertisingInterval ( void   ) const [virtual]
See also:
Gap::getMinNonConnectableAdvertisingInterval

Reimplemented from Gap.

Definition at line 466 of file GenericGap.cpp.

void getPermittedTxPowerValues ( const int8_t **  valueArrayPP,
size_t *  countP 
) [virtual]
See also:
Gap::getPermittedTxPowerValues

Reimplemented from Gap.

Definition at line 643 of file GenericGap.cpp.

ble_error_t getPreferredConnectionParams ( ConnectionParams_t params ) [virtual]
See also:
Gap::getPreferredConnectionParams

Reimplemented from Gap.

Definition at line 569 of file GenericGap.cpp.

Gap::ScanningPolicyMode_t getScanningPolicyMode ( void   ) const [virtual]
See also:
Gap::getScanningPolicyMode

Reimplemented from Gap.

Definition at line 798 of file GenericGap.cpp.

GapState_t getState ( void   ) const [inherited]

Get the current advertising and connection states of the device.

Returns:
The current GAP state of the device.

Definition at line 1406 of file Gap.h.

ble_error_t getWhitelist ( Whitelist_t whitelist ) const [virtual]
See also:
Gap::getWhitelist

Reimplemented from Gap.

Definition at line 653 of file GenericGap.cpp.

ble_error_t initRadioNotification ( void   ) [virtual]
See also:
Gap::initRadioNotification

Reimplemented from Gap.

Definition at line 849 of file GenericGap.cpp.

MBED_DEPRECATED ( "Gap::DeprecatedAddressType_t is   deprecated,
use BLEProtocol::AddressType_t instead"   
) const [inherited]

Initiate a connection to a peer.

See also:
connect()

Definition at line 998 of file Gap.h.

MBED_DEPRECATED ( "Use disconnect(Handle_t, DisconnectionReason_t) instead."   ) [inherited]

Initiate a disconnection procedure.

Parameters:
[in]reasonThe reason for disconnection; to be sent back to the peer.
Returns:
BLE_ERROR_NONE if disconnection was successful.

Definition at line 1051 of file Gap.h.

static uint16_t MSEC_TO_GAP_DURATION_UNITS ( uint32_t  durationInMillis ) [static, inherited]

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.

Definition at line 754 of file Gap.h.

void onConnection ( ConnectionEventCallback_t  callback ) [inherited]

Register a callback handling connection events.

Parameters:
[in]callbackEvent handler being registered.
Note:
A callback may be unregistered using onConnection().detach(callback).

Definition at line 2054 of file Gap.h.

void onConnection ( T *  tptr,
void(T::*)(const ConnectionCallbackParams_t *)  mptr 
) [inherited]

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

Definition at line 2068 of file Gap.h.

ConnectionEventCallbackChain_t& onConnection (  ) [inherited]

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.

Definition at line 2082 of file Gap.h.

void onDisconnection ( DisconnectionEventCallback_t  callback ) [inherited]

Register a callback handling disconnection events.

Parameters:
[in]callbackEvent handler being registered.
Note:
A callback may be unregistered using onDisconnection().detach(callback).

Definition at line 2094 of file Gap.h.

void onDisconnection ( T *  tptr,
void(T::*)(const DisconnectionCallbackParams_t *)  mptr 
) [inherited]

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

Definition at line 2108 of file Gap.h.

DisconnectionEventCallbackChain_t& onDisconnection (  ) [inherited]

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.

Definition at line 2122 of file Gap.h.

void onRadioNotification ( void(*)(bool param)  callback ) [inherited]

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.

Definition at line 2144 of file Gap.h.

void onRadioNotification ( T *  tptr,
void(T::*)(bool)  mptr 
) [inherited]

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.

Definition at line 2157 of file Gap.h.

void onShutdown ( const GapShutdownCallback_t callback ) [inherited]

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

Definition at line 2173 of file Gap.h.

GapShutdownCallbackChain_t& onShutdown (  ) [inherited]

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.

Definition at line 2199 of file Gap.h.

void onShutdown ( T *  objPtr,
void(T::*)(const Gap *)  memberPtr 
) [inherited]

Register a Gap shutdown event handler.

Parameters:
[in]objPtrInstance used to invoke memberPtr.
[in]memberPtrShutdown event handler to register.

Definition at line 2185 of file Gap.h.

TimeoutEventCallbackChain_t& onTimeout (  ) [inherited]

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.

Definition at line 2042 of file Gap.h.

void onTimeout ( TimeoutEventCallback_t  callback ) [inherited]

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

Definition at line 2028 of file Gap.h.

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 
) [inherited]

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.

Definition at line 2353 of file Gap.h.

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 
)

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.

Reimplemented from Gap.

Definition at line 925 of file GenericGap.cpp.

void processDisconnectionEvent ( Handle_t  handle,
DisconnectionReason_t  reason 
)

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.

Reimplemented from Gap.

Definition at line 957 of file GenericGap.cpp.

void processTimeoutEvent ( TimeoutSource_t  source ) [inherited]

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.

Definition at line 2386 of file Gap.h.

ble_error_t reset ( void   ) [virtual]
See also:
Gap::reset

Reimplemented from Gap.

Definition at line 916 of file GenericGap.cpp.

ble_error_t setActiveScanning ( bool  activeScanning ) [inherited]

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.

Definition at line 1863 of file Gap.h.

ble_error_t setAddress ( BLEProtocol::AddressType_t  type,
const BLEProtocol::AddressBytes_t  address 
) [virtual]
See also:
Gap::setAddress

Reimplemented from Gap.

Definition at line 404 of file GenericGap.cpp.

ble_error_t setAdvertisingData ( const GapAdvertisingData advData,
const GapAdvertisingData scanResponse 
) [virtual]
See also:
Gap::setAdvertisingData

Implements Gap.

Definition at line 854 of file GenericGap.cpp.

void setAdvertisingInterval ( uint16_t  interval ) [inherited]

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.

Definition at line 1437 of file Gap.h.

void setAdvertisingParams ( const GapAdvertisingParams newParams ) [inherited]

Set the advertising parameters.

Parameters:
[in]newParamsThe new advertising parameters.

Definition at line 2012 of file Gap.h.

ble_error_t setAdvertisingPayload ( const GapAdvertisingData payload ) [inherited]

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.

Definition at line 1678 of file Gap.h.

ble_error_t setAdvertisingPolicyMode ( AdvertisingPolicyMode_t  mode ) [virtual]
See also:
Gap::setAdvertisingPolicyMode

Reimplemented from Gap.

Definition at line 763 of file GenericGap.cpp.

void setAdvertisingTimeout ( uint16_t  timeout ) [inherited]

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.

Definition at line 1455 of file Gap.h.

void setAdvertisingType ( GapAdvertisingParams::AdvertisingType_t  advType ) [inherited]

Set the advertising type to use during the advertising procedure.

Parameters:
[in]advTypeNew type of advertising to use.

Definition at line 1416 of file Gap.h.

ble_error_t setAppearance ( GapAdvertisingData::Appearance  appearance ) [virtual]
See also:
Gap::setAppearance

Reimplemented from Gap.

Definition at line 623 of file GenericGap.cpp.

ble_error_t setDeviceName ( const uint8_t *  deviceName ) [virtual]
See also:
Gap::setDeviceName

Reimplemented from Gap.

Definition at line 591 of file GenericGap.cpp.

ble_error_t setInitiatorPolicyMode ( InitiatorPolicyMode_t  mode ) [virtual]
See also:
Gap::setInitiatorPolicyMode

Reimplemented from Gap.

Definition at line 783 of file GenericGap.cpp.

ble_error_t setPreferredConnectionParams ( const ConnectionParams_t params ) [virtual]
See also:
Gap::setPreferredConnectionParams

Reimplemented from Gap.

Definition at line 580 of file GenericGap.cpp.

ble_error_t setScanInterval ( uint16_t  interval ) [inherited]

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.

Definition at line 1794 of file Gap.h.

ble_error_t setScanningPolicyMode ( ScanningPolicyMode_t  mode ) [virtual]
See also:
Gap::setScanningPolicyMode

Reimplemented from Gap.

Definition at line 773 of file GenericGap.cpp.

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 
) [inherited]

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.

Definition at line 1768 of file Gap.h.

ble_error_t setScanTimeout ( uint16_t  timeout ) [inherited]

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.

Definition at line 1836 of file Gap.h.

ble_error_t setScanWindow ( uint16_t  window ) [inherited]

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.

Definition at line 1810 of file Gap.h.

ble_error_t setTxPower ( int8_t  txPower ) [virtual]
See also:
Gap::setTxPower

Reimplemented from Gap.

Definition at line 636 of file GenericGap.cpp.

ble_error_t setWhitelist ( const Whitelist_t whitelist ) [virtual]
See also:
Gap::setWhitelist

Reimplemented from Gap.

Definition at line 671 of file GenericGap.cpp.

ble_error_t startAdvertising ( void   ) [inherited]

Start the advertising procedure.

Returns:
BLE_ERROR_NONE if the device started advertising successfully.

Definition at line 1465 of file Gap.h.

ble_error_t startAdvertising ( const GapAdvertisingParams params ) [virtual]
See also:
Gap::startAdvertising

Implements Gap.

Definition at line 870 of file GenericGap.cpp.

ble_error_t startRadioScan ( const GapScanningParams scanningParams ) [virtual]
See also:
Gap::startRadioScan

Reimplemented from Gap.

Definition at line 808 of file GenericGap.cpp.

ble_error_t startScan ( T *  object,
void(T::*)(const AdvertisementCallbackParams_t *params)  callbackMember 
) [inherited]

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

Definition at line 1921 of file Gap.h.

ble_error_t startScan ( void(*)(const AdvertisementCallbackParams_t *params)  callback ) [inherited]

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

Definition at line 1889 of file Gap.h.

ble_error_t stopAdvertising ( void   ) [virtual]
See also:
Gap::stopAdvertising

Reimplemented from Gap.

Definition at line 476 of file GenericGap.cpp.

ble_error_t stopScan (  ) [virtual]
See also:
Gap::stopScan

Reimplemented from Gap.

Definition at line 487 of file GenericGap.cpp.

ble_error_t updateAdvertisingPayload ( GapAdvertisingData::DataType  type,
const uint8_t *  data,
uint8_t  len 
) [inherited]

Update a particular field in the advertising payload.

A call to this function is equivalent to:

 Gap &gap;

 GapAdvertisingData payload = gap.getAdvertisingPayload();
 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.

Definition at line 1652 of file Gap.h.

ble_error_t updateConnectionParams ( Handle_t  handle,
const ConnectionParams_t params 
) [virtual]
See also:
Gap::updateConnectionParams

Reimplemented from Gap.

Definition at line 552 of file GenericGap.cpp.


Field Documentation

GapAdvertisingParams _advParams [protected, inherited]

Current advertising parameters.

Definition at line 2401 of file Gap.h.

GapAdvertisingData _advPayload [protected, inherited]

Current advertising data.

Definition at line 2406 of file Gap.h.

GapScanningParams _scanningParams [protected, inherited]

Current scanning parameters.

Definition at line 2411 of file Gap.h.

GapAdvertisingData _scanResponse [protected, inherited]

Current scan response.

Definition at line 2416 of file Gap.h.

const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN [static, inherited]

Length (in octets) of the BLE MAC address.

Definition at line 305 of file Gap.h.

Callchain containing all registered callback handlers for connection events.

Definition at line 2455 of file Gap.h.

uint8_t connectionCount [protected, inherited]

Number of open connections.

Definition at line 2421 of file Gap.h.

Callchain containing all registered callback handlers for disconnection events.

Definition at line 2461 of file Gap.h.

The registered callback handler for scanned advertisement packet notifications.

Definition at line 2449 of file Gap.h.

The registered callback handler for radio notification events.

Definition at line 2443 of file Gap.h.

bool scanningActive [protected, inherited]

Active scanning flag.

Definition at line 2431 of file Gap.h.

GapState_t state [protected, inherited]

Current GAP state.

Definition at line 2426 of file Gap.h.

Callchain containing all registered callback handlers for timeout events.

Definition at line 2438 of file Gap.h.

const uint16_t UNIT_1_25_MS = 1250 [static, inherited]

Number of microseconds in 1.25 milliseconds.

Definition at line 742 of file Gap.h.